Polypix

Batch coverage of circles, polygons, and swept paths on a HEALPix grid.

Documentation | Changelog | PyPI | Repository | Issues

Hand Polypix a batch of spherical regions and it gives you back the HEALPix cells they cover, as standard RING IDs in NumPy arrays. The spherical geometry runs in a native kernel, which uses several cores for large calls. Use the result for coverage maps, visibility counts, and revisit analysis. Polygon coverage also accepts GeoJSON-like mappings and objects implementing __geo_interface__, including individual Shapely geometries.

How many Starlink satellites can you see?

All 10,771 catalogued Starlink objects, propagated for an hour and counted cell by cell. Two dense bands around 40° north and south see 70 to 90 objects at once, the equator about 37, the poles about 20. Behind it are 137 million cap-cell hits, counted by one cover_cap() call per timestamp, never stored, and done in well under a second.

Read the case study for the propagation, the service-cap geometry, and the timings.

Install

pip install polypix

There are wheels for CPython 3.12 and newer on Linux x86-64 and ARM64, macOS 11+ on Intel and Apple Silicon, and Windows x86-64. NumPy is the only runtime dependency.

Quick start

Two satellites overhead, each serving a circle on the ground. Centers are Cartesian directions and radii are in radians:

import numpy as np
import polypix as px

centers = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
radii = np.radians([6.0, 4.0])

coverage = px.cover_cap(centers, radii, resolution=6)
print(np.diff(coverage.offsets))  # [134  56]

coverage[i] holds the cells covered by satellite i. A cell is covered when its center falls inside the circle, so partial overlap at the boundary does not count. Pass mode="overlap" when every touched cell should count instead.

Ask for counts instead and the region-cell pairs are never built, which is how the map above is made:

counts = px.cover_cap(centers, radii, resolution=6, reduce=px.Count())
print(counts.shape)  # (49152,) one value per cell on the grid

Documentation

Start with Getting started. The site also carries the API reference, a resolution guide, and two constellation case studies that run end to end.

Versioning

Polypix follows semantic versioning. The public API is everything in polypix.__all__.

License

Apache License 2.0. See THIRD_PARTY_NOTICES.md for the dependency and embedded-code notices.