rusterize 0.3.0__cp311-abi3-win_amd64.whl

rusterize/__init__.py

@@ -0,0 +1,4 @@
+import importlib.metadata
+from .core import *
+
+__version__ = importlib.metadata.version("rusterize")

rusterize/core.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from types import NoneType
+from typing import Any, Dict, Tuple
+
+import polars as pl
+from geopandas import GeoDataFrame
+import rioxarray
+from xarray import DataArray
+from .rusterize import _rusterize
+
+
+def rusterize(gdf: GeoDataFrame,
+              res: Tuple[int, ...] | Tuple[float, ...] | None = None,
+              out_shape: Tuple[int, ...] | None = None,
+              extent: Tuple[int, ...] | Tuple[float, ...] | None = None,
+              field: str | None = None,
+              by: str | None = None,
+              fun: str = "last",
+              background: int | float | None = None,
+              ) -> Dict[str, Any]:
+    """
+    Fast geopandas rasterization into xarray.DataArray
+
+    Args:
+        :param gdf: geopandas dataframe to rasterize.
+        :param res: tuple of (xres, yres) for rasterized data.
+        :param out_shape: tuple of (nrows, ncols) for regularized output shape.
+        :param extent: tuple of (xmin, xmax, ymin, ymax) for regularized extent.
+        :param field: field to rasterize. 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 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 None (NaN).
+
+    Returns:
+        Rasterized xarray.DataArray.
+
+    Note:
+        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.
+    """
+    # type checks
+    if not isinstance(gdf, GeoDataFrame):
+        raise TypeError("Must pass a valid geopandas dataframe.")
+    if not isinstance(res, (tuple, NoneType)):
+        raise TypeError("Must pass a valid resolution tuple (x, y).")
+    if not isinstance(out_shape, (tuple, NoneType)):
+        raise TypeError("Must pass a valid output shape tuple (nrows, ncols).")
+    if not isinstance(extent, (tuple, NoneType)):
+        raise TypeError("Must pass a valid extent tuple (xmin, ymin, xmax, ymax).")
+    if not isinstance(field, (str, NoneType)):
+        raise TypeError("Must pass a valid string to field.")
+    if not isinstance(by, (str, NoneType)):
+        raise TypeError("Must pass a valid string to by.")
+    if not isinstance(fun, str):
+        raise TypeError("Must pass a valid string to pixel_fn. Select one of sum, first, last, min, max, count, or any.")
+    if not isinstance(background, (int, float, NoneType)):
+        raise TypeError("Must pass a valid background type.")
+
+    # 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 by and not field:
+        raise ValueError("If `by` is specified, `field` must also 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]))
+    df = pl.from_pandas(gdf[cols]) if cols else None
+
+    # rusterize
+    r = _rusterize(
+        gdf.geometry,
+        raster_info,
+        fun,
+        df,
+        field,
+        by,
+        background
+    )
+    return DataArray.from_dict(r).rio.write_crs(gdf.crs, inplace=True)

rusterize-0.3.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: rusterize
+Version: 0.3.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: fast,raster,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.
+
+**rusterize** is designed to work on *(multi)polygons* and *(multi)linestrings*. 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-01-05
+
+ # 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.core import rusterize
+
+# gdf = <import/modify dataframe as needed>
+
+# rusterize
+rusterize(gdf,
+          res=(30, 30),
+          out_shape=(10, 10)
+          extent=(0, 300, 0, 300)
+          field="field",
+          by="by",
+          fun="sum",
+          background=0) 
+```
+
+- `gdf`: geopandas dataframe to rasterize
+- `res`: tuple of (xres, yres) for desired resolution (default: `None`)
+- `out_shape`: tuple of (nrows, ncols) for desired output shape (default: `None`)
+- `extent`: tuple of (xmin, ymin, xmax, ymax) for desired output extent (default: `None`)
+- `field`: field to rasterize. (default: `None` -> a value of `1` is rasterized).
+- `by`: column to rasterize. Assigns each group to a band in the stack. Values are taken from `field`. (default: `None` -> singleband raster)
+- `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`)
+
+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.core 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))"
+]
+
+# 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.core 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_large       1.6430   1.9249   1.7442  0.1024   1.6878   0.1974      6;0  0.5733      20           1
+rusterize_small       0.0912   0.1194   0.1014  0.0113   0.0953   0.0223      7;0  9.8633      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_large 9.9450280 10.6674467 10.8632224 10.9182963 11.1943478 11.3768210    20
+ fasterize_small 0.4906411  0.5140836  0.5581061  0.5320919  0.5603512  0.8750579    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             6.7270   7.0098   6.7824  0.0646   6.7686   0.0266      2;2  0.1474      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.801 s ±  0.124 s    [User: 4.381 s, System: 1.396 s]
+Range (min … max):    5.649 s …  6.023 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, and extent.
+
+The following is a time comparison on a single run on the same forest stands dataset used earlier.
+```
+rusterize:    6.7 sec
+rasterio:     68  sec (but no spatial information)
+fasterize:    157 sec (including raster creation)
+geocube:      260 sec (larger memory footprint)
+```

rusterize-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rusterize-0.3.0.dist-info/METADATA,sha256=spu-itZ6aACvDps3MbfUaXPUKignwHjgr8_m9Ryd8b4,10435
+rusterize-0.3.0.dist-info/WHEEL,sha256=4qYHF3r3_wk9215EqUuzc4CZ76XfRcqOTn7Cv3gIg80,95
+rusterize-0.3.0.dist-info/licenses/LICENSE,sha256=FXkix0amECHul0Y2qWBXnEGNV2fd8GuVCIZuuzQwR-c,1130
+rusterize/core.py,sha256=b6ciLMbrBCihdQdOVifAg9d2pE0gjX-aj08erPSSDBM,4694
+rusterize/__init__.py,sha256=rQSJ7V7ykrsuWz-cQK5Dm9E7usCYmCD3dIUrnosWABc,105
+rusterize/rusterize.pyd,sha256=-muUoytgSoapAGDQ64QvZptJHex0oYuDIwA0SiIa_X4,40093184
+rusterize-0.3.0.dist-info/RECORD,,

rusterize-0.3.0.dist-info/WHEEL

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

rusterize-0.3.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.