Metadata-Version: 2.4
Name: fastpgv
Version: 0.1.1
Summary: High-performance Polygon-to-Grid Visualization (PGV) tool in Python
Keywords: polygon,raster,geospatial,SLED,aggregation
Author: SLED contributors
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/pybind11-LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: shapely>=2; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: shapely>=2; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Description-Content-Type: text/markdown

# fastpgv

**fastpgv** is a lightweight Python wrapper for fast density computation for Polygon-to-Grid Visualization (PGV).

This package provides an efficient way to compute density results through a simple Python interface.
Compute a density value for every pixel from weighted polygons using the C++17 SLED (Sweep-Line Edge-Difference Aggregation) algorithm.

## Features

- One Python interface: `fastpgv.run(weighted_polygons, resolution)`.
- Weighted polygons with explicit vertex coordinates.
- The polygons should be non-overlapping.
- C++ computation backend with the Python interface.

## Installation

From the `fastpgv/` source directory:

```bash
python -m pip install .
```

After version 0.1.1 is successfully published to production PyPI:

```bash
python -m pip install fastpgv==0.1.1
```

## Requirements

- Python 3.10 or newer.
- NumPy, installed automatically by pip.
- A C++17 compiler for source builds. pip installs the Python build dependencies.

## Quick Example

```python
import fastpgv

# Polygons contain ordered vertex coordinates, not just identifiers.
polygon_a = {
    "type": "Polygon",
    "coordinates": [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]],
}
polygon_b = {
    "type": "Polygon",
    "coordinates": [[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]],
}

density = fastpgv.run(
    [(polygon_a, 2.0), (polygon_b, 3.0)],
    resolution=(2, 1),
)
print(density)
# [[2. 3.]]
```

## Inputs and Output

Both arguments are required:

| Argument | Meaning |
|---|---|
| `weighted_polygons` | Nonempty iterable of `(geometry, weight)` pairs |
| `resolution` | Positive integer `(X, Y)`: columns and rows |

## Notes

- Each pixel value is the sum of `weight * polygon_pixel_intersection_area`:
  **weighted area, not area-normalized density**.
- Coordinates are planar, with no CRS transformation or geodesic calculation.
  Project geographic coordinates first when metric areas are required.
- Supply valid polygon topology. Ring orientation is corrected, but invalid
  holes and self-intersections are not repaired. Empty input is rejected.
- The complete output array requires `8 * X * Y` bytes, plus polygon-edge and
  working storage. Choose a resolution that fits available memory.

## License and Further Information

MIT licensed, by **SLED contributors**.

The source archive includes `PUBLISHING.md` (build and upload instructions),
`PORTING.md` (implementation provenance), and `THIRD_PARTY_NOTICES.md`
(dependency notices).
