rusterize 0.4.0__cp311-abi3-manylinux_2_28_ppc64le.whl

rusterize/__init__.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+import importlib.metadata
+
+from types import NoneType
+from typing import List, Tuple
+
+import numpy as np
+import polars as pl
+from geopandas import GeoDataFrame
+import rioxarray
+from xarray import DataArray
+from .rusterize import _rusterize
+
+__version__ = importlib.metadata.version("rusterize")
+
+
+def rusterize(
+    gdf: GeoDataFrame,
+    res: Tuple | List | None = None,
+    out_shape: Tuple | List | None = None,
+    extent: Tuple | List | None = None,
+    field: str | None = None,
+    by: str | None = None,
+    burn: int | float | None = None,
+    fun: str = "last",
+    background: int | float | None = np.nan,
+    dtype: str = "float64",
+) -> DataArray:
+    """
+    Fast geopandas rasterization into xarray.DataArray
+
+    Args:
+        :param gdf: geopandas dataframe to rasterize.
+        :param res: (xres, yres) for rasterized data.
+        :param out_shape: (nrows, ncols) for regularized output shape.
+        :param extent: (xmin, xmax, ymin, ymax) for regularized extent.
+        :param field: field to rasterize, mutually exclusive with `burn`. Default is None.
+        :param by: column to rasterize, assigns each unique value to a layer in the stack based on field. Default is None.
+        :param burn: burn a value onto the raster, mutually exclusive with `field`. Default is None.
+        :param fun: pixel function to use. Available options are `sum`, `first`, `last`, `min`, `max`, `count`, or `any`. Default is `last`.
+        :param background: background value in final raster. Default is np.nan.
+        :param dtype: specify the output dtype. Default is `float64`.
+
+    Returns:
+        Rasterized xarray.DataArray.
+
+    Notes:
+        When any of `res`, `out_shape`, or `extent` is not provided, it is inferred from the other arguments when applicable.
+        Unless `extent` is specified, a half-pixel buffer is applied to avoid missing points on the border.
+        The logics dictating the final spatial properties of the rasterized geometries follow those of GDAL.
+        
+        If `field` is not in `gdf`, then a default `burn` value of 1 is rasterized.
+        
+        A `None` value for `dtype` corresponds to the default of that dtype. An illegal value for a dtype will be replaced with the default of
+        that dtype. For example, a `background=np.nan` for `dtype="uint8"` will become `background=0`, where `0` is the default for `uint8`.
+    """
+    # type checks
+    if not isinstance(gdf, GeoDataFrame):
+        raise TypeError("`gdf` must be a geopandas dataframe.")
+    if not isinstance(res, (tuple, list, NoneType)):
+        raise TypeError("`resolution` must be a tuple or list of (x, y).")
+    if not isinstance(out_shape, (tuple, list, NoneType)):
+        raise TypeError("`out_shape` must be a tuple or list of (nrows, ncols).")
+    if not isinstance(extent, (tuple, list, NoneType)):
+        raise TypeError("`extent` must be a tuple or list of (xmin, ymin, xmax, ymax).")
+    if not isinstance(field, (str, NoneType)):
+        raise TypeError("`field` must be a string column name.")
+    if not isinstance(by, (str, NoneType)):
+        raise TypeError("`by` must be a string column name.")
+    if not isinstance(burn, (int, float, NoneType)):
+        raise TypeError("`burn` must be an integer or float.")
+    if not isinstance(fun, str):
+        raise TypeError("`pixel_fn` must be one of sum, first, last, min, max, count, or any.")
+    if not isinstance(background, (int, float, NoneType)):
+        raise TypeError("`background` must be integer, float, or None.")
+    if not isinstance(dtype, str):
+        raise TypeError("`dtype` must be a one of uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32, float64")
+
+    # value checks
+    if not res and not out_shape and not extent:
+        raise ValueError("One of `res`, `out_shape`, or `extent` must be provided.")
+    if extent and not res and not out_shape:
+        raise ValueError("Must also specify `res` or `out_shape` with extent.")
+    if res and (len(res) != 2 or any(r <= 0 for r in res) or any(not isinstance(r, (int, float)) for r in res)):
+        raise ValueError("Resolution must be 2 positive numbers.")
+    if out_shape and (len(out_shape) != 2 or any(s <= 0 for s in out_shape) or any(not isinstance(s, int) for s in out_shape)):
+        raise ValueError("Output shape must be 2 positive integers.")
+    if extent and len(extent) != 4:
+        raise ValueError("Extent must be 4 numbers (xmin, ymin, xmax, ymax).")
+    if field and burn:
+        raise ValueError("Only one of `field` or `burn` can be specified.")
+
+    # defaults
+    _res = res if res else (0, 0)
+    _shape = out_shape if out_shape else (0, 0)
+    (_bounds, _has_extent) = (extent, True) if extent else (gdf.total_bounds, False)
+
+    # RasterInfo
+    raster_info = {
+        "nrows": _shape[0],
+        "ncols": _shape[1],
+        "xmin": _bounds[0],
+        "ymin": _bounds[1],
+        "xmax": _bounds[2],
+        "ymax": _bounds[3],
+        "xres": _res[0],
+        "yres": _res[1],
+        "has_extent": _has_extent,
+    }
+
+    # extract columns of interest and convert to polars
+    cols = list(set([col for col in (field, by) if col]))
+    try:
+        df = pl.from_pandas(gdf[cols]) if cols else None
+    except KeyError as e:
+        raise KeyError("Column not found in GeoDataFrame") from e
+
+    # rusterize
+    r = _rusterize(gdf.geometry, raster_info, fun, df, field, by, burn, background, dtype)
+    return DataArray.from_dict(r).rio.write_crs(gdf.crs, inplace=True)

rusterize-0.4.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: rusterize
+Version: 0.4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: geopandas>=1.0.1
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pyarrow>=18.1.0
+Requires-Dist: polars>=1.19.0
+Requires-Dist: xarray>=2025.1.1
+Requires-Dist: rioxarray>=0.18.2
+License-File: LICENSE
+Summary: High performance rasterization tool for Python built in Rust
+Keywords: rust,fast,raster,geometry,geopandas,xarray
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: repository, https://github.com/ttrotto/rusterize
+
+# rusterize
+
+High performance rasterization tool for Python built in Rust. This
+repository stems from the [fasterize](https://github.com/ecohealthalliance/fasterize.git) package built in C++
+for R and ports parts of the logics into Python with a Rust backend, in addition to some useful improvements (see [API](#API)).
+
+**rusterize** is designed to work on *(multi)polygons* and *(multi)linestrings*, even when they are nested inside complex geometry collections. Functionally, it takes an input [geopandas](https://geopandas.org/en/stable/) dataframe and returns a [xarray](https://docs.xarray.dev/en/stable/). 
+
+# Installation
+
+Install the current version with pip:
+
+``` shell
+pip install rusterize
+```
+
+# Contributing
+
+Any contribution is welcome! You can install **rusterize** directly
+from this repo using [maturin](https://www.maturin.rs/) as an editable
+package. For this to work, you’ll need to have [Rust](https://www.rust-lang.org/tools/install) and
+[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
+installed.
+
+``` shell
+# Clone repo
+git clone https://github.com/<username>/rusterize.git
+cd rusterize
+
+# Install the Rust nightly toolchain
+rustup toolchain install nightly-2025-07-31
+
+ # Install maturin
+pip install maturin
+
+# Install editable version with optmized code
+maturin develop --profile dist-release
+```
+
+# API
+
+This package has a simple API:
+
+``` python
+from rusterize import rusterize
+
+# gdf = <import/modify dataframe as needed>
+
+# rusterize
+rusterize(gdf,
+          res=(30, 30),
+          out_shape=(10, 10)
+          extent=(0, 10, 10, 20)
+          field="field",
+          by="by",
+          burn=None,
+          fun="sum",
+          background=0,
+          dtype="uint8") 
+```
+
+- `gdf`: geopandas dataframe to rasterize
+- `res`: (xres, yres) for desired resolution (default: `None`)
+- `out_shape`: (nrows, ncols) for desired output shape (default: `None`)
+- `extent`: (xmin, ymin, xmax, ymax) for desired output extent (default: `None`)
+- `field`: column to rasterize. Mutually exclusive with `burn`. (default: `None` -> a value of `1` is rasterized)
+- `by`: column for grouping. Assign each group to a band in the stack. Values are taken from `field` if specified, else `burn` is rasterized. (default: `None` -> singleband raster)
+- `burn`: a single value to burn. Mutually exclusive with `field`. (default: `None`). If no field is found in `gdf` or if `field` is `None`, then `burn=1`
+- `fun`: pixel function to use when multiple values overlap. Available options are `sum`, `first`, `last`, `min`, `max`, `count`, or `any`. (default: `last`)
+- `background`: background value in final raster. (default: `np.nan`). A `None` value corresponds to the default of the specified dtype. An illegal value for a dtype will be replaced with the default of that dtype. For example, a `background=np.nan` for `dtype="uint8"` will become `background=0`, where `0` is the default for `uint8`.
+- `dtype`: dtype of the final raster. Possible values are `uint8`, `uint16`, `uint32`, `uint64`, `int8`, `int16`, `int32`, `int64`, `float32`, `float64` (default: `float64`)
+
+Note that control over the desired extent is not as strict as for resolution and shape. That is,
+when resolution, output shape, and extent are specified, priority is given to resolution and shape.
+So, extent is not guaranteed, but resolution and shape are. If extent is not given, it is taken
+from the polygons and is not modified, unless you specify a resolution value. If you only specify an output
+shape, the extent is maintained. This mimics the logics of `gdal_rasterize`.
+
+# Usage
+
+**rusterize** consists of a single function `rusterize()`. The Rust implementation
+returns a dictionary that is converted to a xarray on the Python side
+for simpliicty.
+
+``` python
+from rusterize import rusterize
+import geopandas as gpd
+from shapely import wkt
+import matplotlib.pyplot as plt
+
+# Construct geometries
+geoms = [
+    "POLYGON ((-180 -20, -140 55, 10 0, -140 -60, -180 -20), (-150 -20, -100 -10, -110 20, -150 -20))",
+    "POLYGON ((-10 0, 140 60, 160 0, 140 -55, -10 0))",
+    "POLYGON ((-125 0, 0 60, 40 5, 15 -45, -125 0))",
+    "MULTILINESTRING ((-180 -70, -140 -50), (-140 -50, -100 -70), (-100 -70, -60 -50), (-60 -50, -20 -70), (-20 -70, 20 -50), (20 -50, 60 -70), (60 -70, 100 -50), (100 -50, 140 -70), (140 -70, 180 -50))",
+    "GEOMETRYCOLLECTION (POINT (50 -40), POLYGON ((75 -40, 75 -30, 100 -30, 100 -40, 75 -40)), LINESTRING (80 -40, 100 0), GEOMETRYCOLLECTION (POLYGON ((100 20, 100 30, 110 30, 110 20, 100 20))))"
+]
+
+# Convert WKT strings to Shapely geometries
+geometries = [wkt.loads(geom) for geom in geoms]
+
+# Create a GeoDataFrame
+gdf = gpd.GeoDataFrame({'value': range(1, len(geoms) + 1)}, geometry=geometries, crs='EPSG:32619')
+
+# rusterize
+output = rusterize(
+    gdf,
+    res=(1, 1),
+    field="value",
+    fun="sum",
+).squeeze()
+
+# plot it
+fig, ax = plt.subplots(figsize=(12, 6))
+output.plot.imshow(ax=ax)
+plt.show()
+```
+
+![](img/plot.png)
+
+# Benchmarks
+
+**rusterize** is fast! Let’s try it on small and large datasets.
+
+``` python
+from rusterize import rusterize
+import geopandas as gpd
+import requests
+import zipfile
+from io import BytesIO
+
+# large dataset (~380 MB)
+url = "https://s3.amazonaws.com/hp3-shapefiles/Mammals_Terrestrial.zip"
+response = requests.get(url)
+
+# unzip
+with zipfile.ZipFile(BytesIO(response.content), 'r') as zip_ref:
+    zip_ref.extractall()
+    
+# read
+gdf_large = gpd.read_file("Mammals_Terrestrial/Mammals_Terrestrial.shp")
+
+# small dataset (first 1000 rows)
+gdf_small = gdf_large.iloc[:1000, :]
+
+# rusterize at 1/6 degree resolution
+def test_large(benchmark):
+  benchmark(rusterize, gdf_large, res=(1/6, 1/6), fun="sum")
+   
+def test_small(benchmark):
+  benchmark(rusterize, gdf_small, res=(1/6, 1/6), fun="sum")  
+```
+
+Then you can run it with [pytest](https://docs.pytest.org/en/stable/) and [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/):
+```
+pytest <python file> --benchmark-min-rounds=20 --benchmark-time-unit='s'
+
+--------------------------------------------- benchmark: 1 tests --------------------------------------------
+Name (time in s)         Min      Max     Mean  StdDev   Median     IQR  Outliers     OPS  Rounds  Iterations
+-------------------------------------------------------------------------------------------------------------
+rusterize_small       0.0791    0.0899   0.0812  0.0027   0.0803  0.0020       2;2  12.3214     20          1
+rusterize_large     1.379545    1.4474   1.4006  0.0178   1.3966  0.0214       5;1   0.7140     20          1
+-------------------------------------------------------------------------------------------------------------
+```
+And fasterize:
+``` r
+library(sf)
+library(raster)
+library(fasterize)
+library(microbenchmark)
+
+large <- st_read("Mammals_Terrestrial/Mammals_Terrestrial.shp", quiet = TRUE)
+small <- large[1:1000, ]
+fn <- function(v) {
+  r <- raster(v, res = 1/6)
+  return(fasterize(v, r, fun = "sum"))
+}
+microbenchmark(
+  fasterize_large = f <- fn(large),
+  fasterize_small = f <- fn(small),
+  times=20L,
+  unit='s'
+)
+```
+```
+Unit: seconds
+            expr       min         lq       mean     median        uq        max neval
+ fasterize_small 0.4741043  0.4926114  0.5191707  0.5193289  0.536741  0.5859029    20
+ fasterize_large 9.2199426 10.3595465 10.6653139 10.5369429 11.025771 11.7944567    20
+```
+And on an even larger datasets? Here we use a layer from the province of Quebec, Canada representing ~2M polygons of forest stands, rasterized at 30 meters (20 rounds) with no field value and pixel function `any`. The comparison with `gdal_rasterize` was run with `hyperfine --runs 20 "gdal_rasterize -tr 30 30 -burn 1 <data_in> <data_out>"`.
+```
+# rusterize
+--------------------------------------------- benchmark: 1 tests --------------------------------------------
+Name (time in s)         Min      Max     Mean  StdDev   Median     IQR  Outliers     OPS  Rounds  Iterations
+-------------------------------------------------------------------------------------------------------------
+rusterize             5.9331   7.2308   6.1302  0.3183  5.9903   0.1736       2;4  0.1631      20           1
+-------------------------------------------------------------------------------------------------------------
+
+# fasterize
+Unit: seconds
+      expr      min       lq     mean   median       uq      max neval
+ fasterize 157.4734 177.2055 194.3222 194.6455 213.9195 230.6504    20
+
+# gdal_rasterize (CLI) - read from fast drive, write to fast drive
+Time (mean ± σ):      5.495 s ±  0.038 s    [User: 4.268 s, System: 1.225 s]
+Range (min … max):    5.452 s …  5.623 s    20 runs
+```
+In terms of (multi)line rasterization speed, here's a benchmark against `gdal_rasterize` using a layer from the province of Quebec, Canada, representing a subset of the road network for a total of ~535K multilinestrings.
+```
+# rusterize
+--------------------------------------------- benchmark: 1 tests --------------------------------------------
+Name (time in s)         Min      Max     Mean  StdDev   Median     IQR  Outliers     OPS  Rounds  Iterations
+-------------------------------------------------------------------------------------------------------------
+test                  4.5272   5.9488   4.7171  0.3236   4.6360  0.1680       2;2  0.2120      20           1
+-------------------------------------------------------------------------------------------------------------
+
+# gdal_rasterize (CLI) - read from fast drive, write to fast drive
+Time (mean ± σ):      8.719 s ±  0.063 s    [User: 3.782 s, System: 4.917 s]
+Range (min … max):    8.658 s …  8.874 s    20 runs
+```
+# Comparison with other tools
+
+While **rusterize** is fast, there are other fast alternatives out there, including `GDAL`, `rasterio` and `geocube`. However, **rusterize** allows for a seamless, Rust-native processing with similar or lower memory footprint that doesn't require you to leave Python, and returns the geoinformation you need for downstream processing with ample control over resolution, shape, extent, and data type.
+
+The following is a time comparison on a single run on the same forest stands dataset used earlier.
+```
+rusterize:    5.9 sec
+rasterio:     68  sec (but no spatial information)
+fasterize:    157 sec (including raster creation)
+geocube:      260 sec (larger memory footprint)
+```

rusterize-0.4.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rusterize-0.4.0.dist-info/METADATA,sha256=VxdEZ9jhsBsBCzPY-yZiktAmNs4wuSWEe3GpU863CTQ,11176
+rusterize-0.4.0.dist-info/WHEEL,sha256=MGaQjBHAphO6IVR063SFNWIT-ZlGUh0_fKN0-9trTkw,108
+rusterize-0.4.0.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
+rusterize/__init__.py,sha256=TZvnGqurMBCNrnTfdtjkFhQofqUk-w7TO19JhB5m1OQ,5525
+rusterize/rusterize.abi3.so,sha256=8XDkTy4fMGQeErO_QYQgg50UcmAgX_v-u54LHUMcgyo,48538216
+rusterize-0.4.0.dist-info/RECORD,,

rusterize-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.3)
+Root-Is-Purelib: false
+Tag: cp311-abi3-manylinux_2_28_ppc64le

rusterize-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Tommaso Trotto
+Copyright (c) 2017 EcoHealth Alliance
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.