pysupercluster

https://github.com/wemap/pysupercluster
Admin
A fast Python 3 module for geospatial point clustering that efficiently groups nearby geographical...
Tokens:3,230
Snippets:21
Trust Score:7.4
License:ISC
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pysupercluster from source

Source: https://context7.com/wemap/pysupercluster/llms.txt

Installs pysupercluster from its GitHub repository. Requires cloning the repository, ensuring NumPy is installed, and then running the pip install command.

```bash
git clone https://github.com/wemap/pysupercluster
cd pysupercluster
pip install numpy        # ensure NumPy is present before building
pip install .
```

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

### Install pysupercluster using pip

Source: https://github.com/wemap/pysupercluster/blob/master/README.rst

Use pip to install the pysupercluster library. This is the recommended method for installation.

```bash
pip install pysupercluster
```

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

### Basic Usage of pysupercluster

Source: https://github.com/wemap/pysupercluster/blob/master/README.rst

Demonstrates how to initialize SuperCluster with points and retrieve clustered points for a given zoom level and bounding box. Ensure numpy is imported for point array creation.

```python
import numpy
import pysupercluster
points = numpy.array([
    (2.3522, 48.8566),   # paris
    (-0.1278, 51.5074),  # london
    (-0.0077, 51.4826),  # greenwhich
])
index = pysupercluster.SuperCluster(
    points,
    min_zoom=0,
    max_zoom=16,
    radius=40,
    extent=512)
clusters = index.getClusters(
    top_left=(-180, 90),
    bottom_right=(180, -90),
    zoom=4)

```

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

### Programmatic Expansion of Clusters

Source: https://context7.com/wemap/pysupercluster/llms.txt

Iterates through world clusters to find and expand a cluster at its specific zoom level. Requires pre-existing `world_clusters` and `index` objects.

```python
for c in world_clusters:
    if c['expansion_zoom'] is not None:
        sub = index.getClusters(
            top_left=(-180, 90),
            bottom_right=(180, -90),
            zoom=c['expansion_zoom'],
        )
        print(f"\nExpanded cluster {c['id']} at zoom {c['expansion_zoom']}: {len(sub)} items")
        break
```

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

### Run pysupercluster tests

Source: https://context7.com/wemap/pysupercluster/llms.txt

Executes the test suite for pysupercluster using pytest or directly running the test script. Requires the `pytest` package for the first command.

```bash
python -m pytest tests.py -v
# or
python tests.py
```

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

### Build SuperCluster Index with NumPy Points

Source: https://context7.com/wemap/pysupercluster/llms.txt

Constructs a SuperCluster index from a NumPy array of (longitude, latitude) pairs. Ensure points are float64, 2D, and shaped (N, 2). Handles empty array input by raising ValueError.

```python
import numpy
import pysupercluster

# Points shaped (N, 2): each row is (longitude, latitude)
points = numpy.array([
    (2.3522,  48.8566),   # Paris
    (-0.1278, 51.5074),   # London
    (-0.0077, 51.4826),   # Greenwich
    (13.4050, 52.5200),   # Berlin
    (2.1734,  41.3851),   # Barcelona
    (12.4964, 41.9028),   # Rome
], dtype=numpy.float64)

# Build the index. Parameters:
#   min_zoom : lowest zoom level to pre-compute (default 0)
#   max_zoom : highest zoom level to pre-compute (default 16)
#   radius   : cluster radius in pixels (default 40)
#   extent   : tile extent in pixels (default 512)
index = pysupercluster.SuperCluster(
    points,
    min_zoom=0,
    max_zoom=16,
    radius=40,
    extent=512,
)
# index is now ready for repeated getClusters() queries.

# Validation: passing an empty array raises ValueError
try:
    bad = pysupercluster.SuperCluster(numpy.ones((0, 2)), min_zoom=0, max_zoom=16, radius=40, extent=512)
except ValueError as e:
    print(f"Error: {e}")
# Error: Array must be of type double and 2 dimensional and must have a length >= 1.
```

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

### pysupercluster.SuperCluster(points, min_zoom, max_zoom, radius, extent)

Source: https://context7.com/wemap/pysupercluster/llms.txt

Constructs a SuperCluster index from a NumPy array of geographic coordinates. The index is built once at all zoom levels between min_zoom and max_zoom using the provided radius (in pixels) and tile extent.

```APIDOC
## pysupercluster.SuperCluster(points, min_zoom, max_zoom, radius, extent)

### Description
Constructs a `SuperCluster` index from a NumPy array of geographic coordinates. The index is built once at all zoom levels between `min_zoom` and `max_zoom` using the provided `radius` (in pixels) and tile `extent`. The `points` array must be of dtype `float64`, two-dimensional, shaped `(N, 2)`, with columns ordered as `(longitude, latitude)`, and must contain at least one point.

### Parameters
#### Path Parameters
- **points** (numpy.ndarray) - Required - A NumPy array of (longitude, latitude) pairs.
- **min_zoom** (int) - Optional - The lowest zoom level to pre-compute (default 0).
- **max_zoom** (int) - Optional - The highest zoom level to pre-compute (default 16).
- **radius** (int) - Optional - The cluster radius in pixels (default 40).
- **extent** (int) - Optional - The tile extent in pixels (default 512).

### Request Example
```python
import numpy
import pysupercluster

points = numpy.array([
    (2.3522,  48.8566),   # Paris
    (-0.1278, 51.5074),   # London
    (-0.0077, 51.4826),   # Greenwich
    (13.4050, 52.5200),   # Berlin
    (2.1734,  41.3851),   # Barcelona
    (12.4964, 41.9028),   # Rome
], dtype=numpy.float64)

index = pysupercluster.SuperCluster(
    points,
    min_zoom=0,
    max_zoom=16,
    radius=40,
    extent=512,
)
```

### Error Handling
- Passing an empty array for `points` raises a `ValueError`.
```

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

### SuperCluster.getClusters(top_left, bottom_right, zoom)

Source: https://context7.com/wemap/pysupercluster/llms.txt

Returns a list of cluster/point dictionaries that fall within the bounding box defined by top_left and bottom_right at the given integer zoom level.

```APIDOC
## SuperCluster.getClusters(top_left, bottom_right, zoom)

### Description
Returns a list of cluster/point dictionaries that fall within the bounding box defined by `top_left=(lng, lat)` and `bottom_right=(lng, lat)` at the given integer `zoom` level. Each returned dictionary contains information about the cluster or individual point.

### Parameters
#### Path Parameters
- **top_left** (tuple) - Required - The top-left corner of the bounding box as (longitude, latitude).
- **bottom_right** (tuple) - Required - The bottom-right corner of the bounding box as (longitude, latitude).
- **zoom** (int) - Required - The integer zoom level for the query.

### Response
#### Success Response
Each item in the returned list is a dictionary with the following keys:
- **id** (int) - Unique cluster identifier.
- **count** (int) - Number of original points in this cluster (1 indicates an individual point).
- **latitude** (float) - Centroid latitude of the cluster.
- **longitude** (float) - Centroid longitude of the cluster.
- **expansion_zoom** (int | None) - The zoom level at which this cluster expands into sub-clusters. This is `None` for individual points.

### Request Example
```python
import numpy
import pysupercluster

points = numpy.array([
    (2.3522,  48.8566),   # Paris
    (-0.1278, 51.5074),   # London
    (-0.0077, 51.4826),   # Greenwich
    (13.4050, 52.5200),   # Berlin
    (2.1734,  41.3851),   # Barcelona
    (12.4964, 41.9028),   # Rome
], dtype=numpy.float64)

index = pysupercluster.SuperCluster(points, min_zoom=0, max_zoom=16, radius=40, extent=512)

# Query for clusters within a bounding box at a specific zoom level
clusters = index.getClusters(
    top_left=(-180, 90),
    bottom_right=(180, -90),
    zoom=2,
)

for c in clusters:
    print(c)
```

### Response Example
```json
{
  "id": 0,
  "count": 3,
  "expansion_zoom": 4,
  "latitude": 47.38,
  "longitude": 5.97
}
```
```

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

### Query Clusters within Bounding Box

Source: https://context7.com/wemap/pysupercluster/llms.txt

Retrieves clusters or individual points within a specified bounding box at a given zoom level. Each result includes cluster ID, point count, centroid coordinates, and expansion zoom level.

```python
import numpy
import pysupercluster

points = numpy.array([
    (2.3522,  48.8566),   # Paris
    (-0.1278, 51.5074),   # London
    (-0.0077, 51.4826),   # Greenwich
    (13.4050, 52.5200),   # Berlin
    (2.1734,  41.3851),   # Barcelona
    (12.4964, 41.9028),   # Rome
], dtype=numpy.float64)

index = pysupercluster.SuperCluster(points, min_zoom=0, max_zoom=16, radius=40, extent=512)

# --- World-wide view at low zoom (expect heavy clustering) ---
world_clusters = index.getClusters(
    top_left=(-180, 90),
    bottom_right=(180, -90),
    zoom=2,
)
print("Zoom 2 (world):")
for c in world_clusters:
    print(c)
# Example output:
# {'id': 0, 'count': 3, 'expansion_zoom': 4, 'latitude': 47.38..., 'longitude': 5.97...}
# {'id': 1, 'count': 3, 'expansion_zoom': 5, 'latitude': 48.61..., 'longitude': 8.46...}

# --- European bounding box at mid zoom (clusters begin to split) ---

europe_clusters = index.getClusters(
    top_left=(-10, 60),
    bottom_right=(20, 35),
    zoom=4,
)
print("\nZoom 4 (Europe):")
for c in europe_clusters:
    print(c)

# --- Street-level zoom (individual points, count == 1) ---

london_area = index.getClusters(
    top_left=(-0.2, 51.6),
    bottom_right=(0.1, 51.4),
    zoom=12,
)
print("\nZoom 12 (London area):")
for c in london_area:
    if c['count'] == 1:
        print(f"  Individual point  lat={c['latitude']:.4f} lng={c['longitude']:.4f}")
    else:
        print(f"  Cluster of {c['count']} points, expands at zoom {c['expansion_zoom']}")

```
Tokens:
Raw