Pyquadkey2

https://docs.muetsch.io/pyquadkey2
Admin
Pyquadkey2 is a feature-rich Python implementation of QuadKeys, a geographical tiling system...
Tokens:5,261
Snippets:25
Trust Score:8.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install pyquadkey2 from Archive

Source: https://docs.muetsch.io/pyquadkey2/installation

Installs the pyquadkey2 library from a downloaded tar.gz archive. This method is useful if you need to install a specific version or prefer not to use pip directly for the download.

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

--------------------------------

### Compile and Install pyquadkey2 from Source (Linux)

Source: https://docs.muetsch.io/pyquadkey2/installation

Builds and installs the pyquadkey2 library from its source code on Linux. Requires development tools like gcc and python3-devel, and uses pip to install dependencies and the library itself.

```bash
# 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 dependencies
$ pip install -r requirements.txt

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

# Install as module
$ pip install .
```

--------------------------------

### Install pyquadkey2 using Pip

Source: https://docs.muetsch.io/pyquadkey2/installation

Installs the pyquadkey2 library using the pip package installer. This is the recommended method for most users. Tested primarily on Linux and Mac; Windows users may encounter issues and are encouraged to report them.

```bash
$ pip install pyquadkey2
```

--------------------------------

### Get Nearby QuadKeys within a Radius

Source: https://docs.muetsch.io/pyquadkey2/methods

Finds QuadKeys at the same level that are in the current key's neighborhood. The 'n' parameter defines the rectangular radius of the neighborhood to consider. This is useful for proximity searches and spatial analysis.

```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('032')
qk.nearby()     # -> ['021', '031', '023', '033', '201', '032', '030', '211', '210']
qk.nearby(n=2)  # -> ['023', '012', '022', '212', '210', '021', '033', '300', '203', '200', '030', '102', '003', '031', '302', '201', '032', '202', '120', '213', '002', '013', '122', '211', '020']
```

--------------------------------

### Get Children QuadKeys at a Specific Level

Source: https://docs.muetsch.io/pyquadkey2/methods

Retrieves all child QuadKeys of the current QuadKey down to a specified level. The target level must be less than the current QuadKey's level. This method is useful for hierarchical spatial indexing and subdivision.

```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
qk.children(at_level=2) # -> ['000', '001', '002', '003', '010', '011', '012', '013', '020', '021', '022', '023', '030', '031', '032', '033']
```

--------------------------------

### QuadKey Methods

Source: https://docs.muetsch.io/pyquadkey2/methods

Documentation for instance methods of the QuadKey class.

```APIDOC
## children

### Description
Get all children of the specified level.

### Method
`children(self, at_level: int = -1) -> List['QuadKey']`

### Parameters
#### Query Parameters
- **at_level** (int) - Optional - Level of the children keys to be returned. Has to be less than the current QuadKey's level.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
qk.children(at_level=2)
```

### Response
#### Success Response (200)
- **List[QuadKey]**: A list of child QuadKey objects.

### Response Example
```json
["000", "001", "002", "003", "010", "011", "012", "013", "020", "021", "022", "023", "030", "031", "032", "033"]
```

## parent

### Description
Get the immediate parent QuadKey.

### Method
`parent(self) -> 'QuadKey'`

### Parameters
None

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('012')
qk.parent()
```

### Response
#### Success Response (200)
- **QuadKey**: The parent QuadKey object.

### Response Example
```json
"01"
```

## nearby

### Description
Get all QuadKeys at the same level that are in the current key's neighborhood of the specified radius `n`.

### Method
`nearby(self, n: int = 1) -> List[str]`

### Parameters
#### Query Parameters
- **n** (int) - Optional - Rectangular "radius" to consider.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('032')
qk.nearby()     # -> ['021', '031', '023', '033', '201', '032', '030', '211', '210']
qk.nearby(n=2)  # -> ['023', '012', '022', '212', '210', '021', '033', '300', '203', '200', '030', '102', '003', '031', '302', '201', '032', '202', '120', '213', '002', '013', '122', '211', '020']
```

### Response
#### Success Response (200)
- **List[str]**: A list of QuadKey strings representing nearby keys.

### Response Example
```json
["021", "031", "023", "033", "201", "032", "030", "211", "210"]
```

## is_ancestor

### Description
Whether or not the given key is an ancestor of the current one.

### Method
`is_ancestor(self, node: 'QuadKey')`

### Parameters
#### Path Parameters
- **node** (QuadKey) - Required - The other QuadKey to check against.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk1 = QuadKey('0')
qk2 = QuadKey('012')
qk1.is_ancestor(qk2)
```

### Response
#### Success Response (200)
- **bool**: True if `node` is an ancestor, False otherwise.

### Response Example
```json
true
```

## is_descendent

### Description
Whether or not the given key is a descendent of the current one.

### Method
`is_descendent(self, node: 'QuadKey')`

### Parameters
#### Path Parameters
- **node** (QuadKey) - Required - The other QuadKey to check against.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk1 = QuadKey('012')
qk2 = QuadKey('0')
qk1.is_descendent(qk2)
```

### Response
#### Success Response (200)
- **bool**: True if `node` is a descendent, False otherwise.

### Response Example
```json
false
```

## side

### Description
Side length in meters of the current key's square projected onto a two-dimensional world map.

### Method
`side(self) -> float`

### Parameters
None

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
qk.side()
```

### Response
#### Success Response (200)
- **float**: The side length in meters.

### Response Example
```json
20037508.342789244
```

## area

### Description
Area in m² of the current key's square projected onto a two-dimensional world map.

### Method
`area(self) -> float`

### Parameters
None

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
qk.area()
```

### Response
#### Success Response (200)
- **float**: The area in square meters.

### Response Example
```json
4.015044337770617e+14
```

## difference

### Description
Returns all keys of the same level that are "between" (in two-dimensional space) the current key and a given one.

### Method
`difference(self, to: 'QuadKey') -> List['QuadKey']`

### Parameters
#### Path Parameters
- **to** (QuadKey) - Required - The second QuadKey.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk1 = QuadKey('032')
qk2 = QuadKey('011')
qk1.difference(qk2)
```

### Response
#### Success Response (200)
- **List[QuadKey]**: A list of QuadKey objects between `self` and `to`.

### Response Example
```json
["011", "013", "031", "033", "010", "012", "030", "032"]
```

## to_tile

### Description
Returns the current key as a tile-tuple and the corresponding level.

### Method
`to_tile(self) -> Tuple[Tuple[int, int], int]`

### Parameters
None

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('032')
qk.to_tile()
```

### Response
#### Success Response (200)
- **Tuple[Tuple[int, int], int]**: A tuple containing the tile coordinates (x, y) and the level.

### Response Example
```json
[[3, 2], 2]
```

## to_pixel

### Description
Returns the current key as a pixel in a two-dimensional matrix.

### Method
`to_pixel(self, anchor: TileAnchor = TileAnchor.ANCHOR_NW) -> Tuple[int, int]`

### Parameters
#### Query Parameters
- **anchor** (TileAnchor) - Optional - "Corner" of the current QuadKey's square / tile to get the pixel value for. Choices are: `ANCHOR_NW`, `ANCHOR_SW`, `ANCHOR_NE`, `ANCHOR_SE`, `ANCHOR_CENTER`.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey, TileAnchor
qk = QuadKey('032')
qk.to_pixel(anchor=TileAnchor.ANCHOR_NW)
```

### Response
#### Success Response (200)
- **Tuple[int, int]**: A tuple representing the pixel coordinates (x, y).

### Response Example
```json
[2, 1]
```

## to_geo

### Description
Returns the current key as GPS coordinates.

### Method
`to_geo(self, anchor: TileAnchor = TileAnchor.ANCHOR_NW) -> Tuple[float, float]`

### Parameters
#### Query Parameters
- **anchor** (TileAnchor) - Optional - "Corner" of the current QuadKey's square / tile to get the geo coordinate value for. Choices are: `ANCHOR_NW`, `ANCHOR_SW`, `ANCHOR_NE`, `ANCHOR_SE`, `ANCHOR_CENTER`.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey, TileAnchor
qk = QuadKey('032')
qk.to_geo(anchor=TileAnchor.ANCHOR_NW)
```

### Response
#### Success Response (200)
- **Tuple[float, float]**: A tuple representing the geographic coordinates (latitude, longitude).

### Response Example
```json
[70.00000000000001, 135.0]
```

## to_quadint

### Description
Returns the current key as a 64-bit integer for better space efficiency.

### Method
`to_quadint(self) -> int`

### Parameters
None

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('032')
qk.to_quadint()
```

### Response
#### Success Response (200)
- **int**: The 64-bit integer representation of the QuadKey.

### Response Example
```json
13743895347234
```
```

--------------------------------

### QuadKey Static Methods

Source: https://docs.muetsch.io/pyquadkey2/methods

Documentation for static methods of the QuadKey class.

```APIDOC
## QuadKey.bbox

### Description
Similar to difference, but as a static method. In addition this method accepts multiple keys and returns all keys that are contained in a bounding box spanned by the two outer-most `quadkeys`.

### Method
`bbox(quadkeys: List['QuadKey']) -> List['QuadKey']`

### Parameters
#### Path Parameters
- **quadkeys** (List[QuadKey]) - Required - A list of QuadKey objects to determine the bounding box.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
qks = [QuadKey('032'), QuadKey('011')]
QuadKey.bbox(qks)
```

### Response
#### Success Response (200)
- **List[QuadKey]**: A list of QuadKey objects within the bounding box.

### Response Example
```json
["011", "013", "031", "033", "010", "012", "030", "032"]
```

## QuadKey.from_geo

### Description
Creates a QuadKey instance from geographic coordinates (latitude, longitude) at a given level. This is an alternative way to instantiate a QuadKey, similar to direct instantiation.

### Method
`from_geo(geo: Tuple[float, float], level: int) -> 'QuadKey'`

### Parameters
#### Path Parameters
- **geo** (Tuple[float, float]) - Required - A tuple containing latitude and longitude.
- **level** (int) - Required - The zoom level for the QuadKey.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
QuadKey.from_geo((70.0, 135.0), 2)
```

### Response
#### Success Response (200)
- **QuadKey**: The QuadKey instance created from the geographic coordinates.

### Response Example
```json
"032"
```

## QuadKey.from_str

### Description
Creates a QuadKey instance from its string representation. This is an alternative way to instantiate a QuadKey, similar to direct instantiation.

### Method
`from_str(qk_str: str) -> 'QuadKey'`

### Parameters
#### Path Parameters
- **qk_str** (str) - Required - The string representation of the QuadKey.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
QuadKey.from_str('032')
```

### Response
#### Success Response (200)
- **QuadKey**: The QuadKey instance created from the string.

### Response Example
```json
"032"
```

## QuadKey.from_int

### Description
Creates a QuadKey instance from its 64-bit integer representation. This is an alternative way to instantiate a QuadKey, similar to direct instantiation.

### Method
`from_int(qk_int: int) -> 'QuadKey'`

### Parameters
#### Path Parameters
- **qk_int** (int) - Required - The 64-bit integer representation of the QuadKey.

### Request Example
```python
from pyquadkey2.quadkey import QuadKey
QuadKey.from_int(13743895347234)
```

### Response
#### Success Response (200)
- **QuadKey**: The QuadKey instance created from the integer.

### Response Example
```json
"032"
```
```

--------------------------------

### Static Methods for QuadKey Instantiation

Source: https://docs.muetsch.io/pyquadkey2/methods

Provides static methods to create QuadKey objects from different data types, including geographic coordinates (geo), string representations, and 64-bit integers. These methods simplify the process of initializing QuadKeys from various sources.

```python
from pyquadkey2.quadkey import QuadKey

# from_geo example:
geo_coords = (37.7749, -122.4194)  # San Francisco
level = 10
qk_from_geo = QuadKey.from_geo(geo_coords, level)

# from_str example:
qk_str = '03213'
qk_from_str = QuadKey.from_str(qk_str)

# from_int example:
qk_int = 1234567890123456789 # Example integer
qk_from_int = QuadKey.from_int(qk_int)
```

--------------------------------

### QuadKey Instantiation

Source: https://docs.muetsch.io/pyquadkey2/instantiation

This section details the three methods for creating a QuadKey object: from a string representation, from an integer representation, or from geographic coordinates.

```APIDOC
## Instantiation Methods

There are three ways of instantiating a QuadKey.

### From string representation

Creates a new `QuadKey` object from a tile's string representation.

#### Method
`from_str(qk_str: str) -> 'QuadKey'`

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

### Request Example
```python
from pyquadkey2 import quadkey
qk = quadkey.from_str('010302121')
```

### Response
#### Success Response (200)
- **qk** (`QuadKey`) - The instantiated QuadKey object.

#### Response Example
```
010302121
```

---

### From integer representation

Creates a new `QuadKey` object from a tile's integer representation.

#### Method
`from_int(qk_int: int) -> 'QuadKey'`

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

### Request Example
```python
from pyquadkey2 import quadkey
qk = quadkey.from_int(1379860704579813385)
```

### Response
#### Success Response (200)
- **qk** (`QuadKey`) - The instantiated QuadKey object.

#### Response Example
```
010302121
```

---

### From coordinates

Creates a new `QuadKey` object from WGS 84 lat/lon coordinates.

#### Method
`from_geo(geo: Tuple[float, float], level: int) -> 'QuadKey'`

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

### Request Example
```python
from pyquadkey2 import quadkey
qk = quadkey.from_geo((49.011011, 8.414971), 9)
```

### Response
#### Success Response (200)
- **qk** (`QuadKey`) - The instantiated QuadKey object.

#### Response Example
```
120203233
```
```

--------------------------------

### Instantiate QuadKey from String - pyquadkey2

Source: https://docs.muetsch.io/pyquadkey2/instantiation

Creates a new QuadKey object from its string representation. This method takes a string representing the tile and returns a QuadKey object. It is a direct way to initialize a QuadKey if its string form is known.

```python
from pyquadkey2 import quadkey
qk = quadkey.from_str('010302121')                  # -> 010302121
```

--------------------------------

### Static Method to Calculate Bounding Box of QuadKeys

Source: https://docs.muetsch.io/pyquadkey2/methods

A static method that computes the bounding box encompassing a list of QuadKeys. It identifies the outer-most keys and returns all QuadKeys contained within the box defined by them. This is useful for spatial query optimization and data aggregation.

```python
from pyquadkey2.quadkey import QuadKey
qks = [QuadKey('032'), QuadKey('011')]
QuadKey.bbox(qks)  # -> [011, 013, 031, 033, 010, 012, 030, 032]
```

--------------------------------

### Convert QuadKey to Tile, Pixel, Geo, and QuadInt Formats

Source: https://docs.muetsch.io/pyquadkey2/methods

Provides methods to convert a QuadKey object into various representations: a tile-tuple with its level, pixel coordinates, GPS coordinates, and a space-efficient 64-bit integer. These conversions are essential for interoperability with different mapping systems and for optimizing storage.

```python
# to_tile example:
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
tile_tuple, level = qk.to_tile()

# to_pixel example:
from pyquadkey2.quadkey import QuadKey, TileAnchor
qk = QuadKey('0')
pixel_coords = qk.to_pixel(anchor=TileAnchor.ANCHOR_NW)

# to_geo example:
from pyquadkey2.quadkey import QuadKey, TileAnchor
qk = QuadKey('0')
geo_coords = qk.to_geo(anchor=TileAnchor.ANCHOR_CENTER)

# to_quadint example:
from pyquadkey2.quadkey import QuadKey
qk = QuadKey('0')
quad_int = qk.to_quadint()
```

--------------------------------

### Instantiate QuadKey from Integer - pyquadkey2

Source: https://docs.muetsch.io/pyquadkey2/instantiation

Creates a new QuadKey object from its integer representation. This method converts an integer tile representation into a QuadKey object. It's useful when dealing with integer-based tile IDs.

```python
from pyquadkey2 import quadkey
qk = quadkey.from_int(1379860704579813385)          # -> 010302121
```

--------------------------------

### Instantiate QuadKey from Coordinates - pyquadkey2

Source: https://docs.muetsch.io/pyquadkey2/instantiation

Creates a new QuadKey object from WGS 84 latitude and longitude coordinates and a zoom level. This method allows for the creation of QuadKey objects based on geographical positions, commonly used in mapping applications.

```python
from pyquadkey2 import quadkey
qk = quadkey.from_geo((49.011011, 8.414971), 9)     # -> 120203233
```

--------------------------------

### Find QuadKeys Between Two QuadKeys

Source: https://docs.muetsch.io/pyquadkey2/methods

Calculates and returns a list of QuadKeys at the same level that lie 'between' the current QuadKey and a specified target QuadKey in two-dimensional space. This method is useful for defining spatial ranges or areas.

```python
from pyquadkey2.quadkey import QuadKey
qk1 = QuadKey('032')
qk2 = QuadKey('011')
qk1.difference(qk1) # -> [011, 013, 031, 033, 010, 012, 030, 032]
```
Tokens:
Raw