rusterize 0.1.0__cp310-abi3-macosx_10_12_x86_64.whl → 0.2.0__cp310-abi3-macosx_10_12_x86_64.whl

rusterize/core.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from types import NoneType
 from typing import Any, Dict, Optional, Tuple, Union
 
 import polars as pl
@@ -10,7 +11,9 @@ from .rusterize import _rusterize
 
 
 def rusterize(gdf: DataFrame,
-              res: Union[Tuple[int, ...], Tuple[float, ...]],
+              res: Optional[Union[Tuple[int, ...], Tuple[float, ...]]] = None,
+              out_shape: Optional[Union[Tuple[int, ...]]] = None,
+              extent: Optional[Union[Tuple[int, ...], Tuple[float, ...]]] = None,
               field: Optional[str] = None,
               by: Optional[str] = None,
               fun: str = "last",
@@ -20,47 +23,71 @@ def rusterize(gdf: DataFrame,
     Fast geopandas rasterization into xarray.DataArray
 
     Args:
-    :param gdf: geopandas dataframe to rasterize.
-    :param res: tuple of (xres, yres) for rasterized data.
-    :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, see fasterize for options. Default is `last`.
-    :param background: background value in final raster. Default is None.
+        :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, see fasterize for options. Default is `last`.
+        :param background: background value in final raster. Default is None.
 
     Returns:
-        Dictionary containing rasterized geometries and spatial attributes to build a xarray.DataArray.
+        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, DataFrame):
         raise TypeError("Must pass a valid geopandas dataframe.")
-    if not isinstance(field, (str, type(None))):
+    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, type(None))):
+    if not isinstance(by, (str, NoneType)):
         raise TypeError("Must pass a valid string to by.")
-    if not isinstance(res, tuple):
-        raise TypeError("Must pass a valid resolution tuple (x, y).")
     if not isinstance(fun, str):
         raise TypeError("Must pass a valid string to pixel_fn. Select only of sum, first, last, min, max, count, or any.")
-    if not isinstance(background, (int, float, type(None))):
+    if not isinstance(background, (int, float, NoneType)):
         raise TypeError("Must pass a valid background type.")
 
     # value check
+    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.")
-    if len(res) != 2 or any((res[0], res[1])) <= 0 or not isinstance(res[0], type(res[1])):
-        raise ValueError("Must pass valid resolution tuple of values of consistent dtype.")
+
+    # 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
-    bounds = gdf.total_bounds
     raster_info = {
-        "xmin": bounds[0],
-        "ymin": bounds[1],
-        "xmax": bounds[2],
-        "ymax": bounds[3],
-        "xres": res[0],
-        "yres": res[1],
-        "nrows": 0,
-        "ncols": 0
+        "xmin": _bounds[0],
+        "ymin": _bounds[1],
+        "xmax": _bounds[2],
+        "ymax": _bounds[3],
+        "xres": _res[0],
+        "yres": _res[1],
+        "nrows": _shape[0],
+        "ncols": _shape[1],
+        "has_extent": has_extent
     }
 
     # extract columns of interest and convert to polars

{rusterize-0.1.0.dist-info → rusterize-0.2.0.dist-info}/METADATA

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: rusterize
-Version: 0.1.0
+Version: 0.2.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
+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 build in Rust
+Summary: High performance rasterization tool for Python built in Rust
 Keywords: fast,raster
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
@@ -21,20 +21,17 @@ Project-URL: repository, https://github.com/ttrotto/rusterize
 
 # rusterize
 
-High performance rasterization tool for python built in Rust. This
-repository is heavily based on the [**fasterize**](https://github.com/ecohealthalliance/fasterize.git) package built in C++
-for R. This version ports it to Python with a Rust backend.
+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.
 
-Functionally, it takes an input [geopandas](https://geopandas.org/en/stable/)
-dataframes and returns a [xarray](https://docs.xarray.dev/en/stable/). It
-tighly mirrors the processing routine of fasterize, so it works only on
-(multi)polygon geometries at the moment.
+**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}
+``` shell
 pip install rusterize
 ```
 
@@ -46,7 +43,7 @@ package. For this to work, you’ll need to have [Rust](https://www.rust-lang.or
 [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
 installed.
 
-``` {shell}
+``` shell
 # Clone repo
 git clone https://github.com/<username>/rusterize.git
 cd rusterize
@@ -65,33 +62,43 @@ maturin develop --profile dist-release
 
 This function has a simple API:
 
-``` {shell}
+``` python
 from rusterize.core import rusterize
 
-# gdf = <import datasets as needed>
+# gdf = <import/modify dataframe as needed>
 
 # rusterize
 rusterize(gdf,
-          (30, 30),
-          "field",
-          "by",
-          "sum",
-          0) 
+          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 final resolution
+- `res`: tuple of (xres, yres) for desired resolution
+- `out_shape`: tuple of (nrows, ncols) for desired output shape
+- `extent`: tuple of (xmin, ymin, xmax, ymax) for desired output extent
 - `field`: field to rasterize. Default is 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 is None
+  stack. Values are taken from `field`. Default is None (singleband raster)
 - `fun`: pixel function to use when multiple values overlap. Default is
   `last`. Available options are `sum`, `first`, `last`, `min`, `max`, `count`, or `any`
 - `background`: background value in final raster. Default is None (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 an array that is then converted to a xarray on the Python side
+returns an array that is converted to a xarray on the Python side
 for simpliicty.
 
 ``` python
@@ -101,17 +108,18 @@ from shapely import wkt
 import matplotlib.pyplot as plt
 
 # example from fasterize
-polygons = [
+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))"
+    "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(polygon) for polygon in polygons]
+geometries = [wkt.loads(geom) for geom in geoms]
 
 # Create a GeoDataFrame
-gdf = gpd.GeoDataFrame({'value': range(1, len(polygons) + 1)}, geometry=geometries, crs='EPSG:32619')
+gdf = gpd.GeoDataFrame({'value': range(1, len(geoms) + 1)}, geometry=geometries, crs='EPSG:32619')
 
 # rusterize
 output = rusterize(
@@ -127,12 +135,11 @@ output.plot.imshow(ax=ax)
 plt.show()
 ```
 
-![](README_files/figure-commonmark/cell-2-output-1.png)
+![](img/plot.png)
 
 # Benchmarks
 
-**fasterize** is fast and so is **rusterize**! Let’s try it on small and large
-datasets.
+**rusterize** is fast! Let’s try it on small and large datasets.
 
 ``` python
 from rusterize.core import rusterize
@@ -167,7 +174,7 @@ Then you can run it with [pytest](https://docs.pytest.org/en/stable/)
 and
 [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/):
 
-``` {shell}
+```
 pytest <python file> --benchmark-min-rounds=20 --benchmark-time-unit='s'
 
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
@@ -180,7 +187,7 @@ test_small            0.5083   0.6416   0.5265  0.0393   0.5120  0.0108       2;
 
 And fasterize:
 
-``` {r}
+``` r
 large <- st_read("Mammals_Terrestrial/Mammals_Terrestrial.shp", quiet = TRUE)
 small <- large[1:1000, ]
 fn <- function(v) {
@@ -195,7 +202,7 @@ microbenchmark(
 )
 ```
 
-``` {shell}
+```
 Unit: seconds
       expr             min        lq      mean    median        uq       max  neval
  fasterize_large  9.565781  9.815375  10.02838  9.984965  10.18532  10.66656     20
@@ -207,7 +214,7 @@ And on even
 datasets? This is a benchmark with 350K+ geometries rasterized at 30
 meters (20 rounds) with no field value and pixel function `sum`.
 
-``` {shell}
+```
 # rusterize
 --------------------------------------------- benchmark: 1 tests --------------------------------------------
 Name (time in s)         Min      Max     Mean  StdDev   Median     IQR  Outliers     OPS  Rounds  Iterations
@@ -221,14 +228,16 @@ Unit: seconds
  fasterize 62.12409 72.13832 74.53424 75.12375 77.72899 84.77415    20
 ```
 
+In terms of (multi)line rasterization speed, here's a benchmark against `gdal_rasterize` using a layer from the province of Quebec, Canada, representing water courses for a total of ~4.5 million multilinestrings.  
+
 # Comparison with other tools
 
-While `rusterize` is fast, there are other very fast solutions out there, including
+While **rusterize** is fast, there are other fast alternatives out there, including:
 - `GDAL`
 - `rasterio`
 - `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.
+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 run on a dataset with 340K+ geometries, rasterized at 2m resolution.
 ```

rusterize-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rusterize-0.2.0.dist-info/METADATA,sha256=m_0TCBYklNLCwsmLrN1Cd1lWP-zdxFikhL-HvxvsdL8,9035
+rusterize-0.2.0.dist-info/WHEEL,sha256=eNkHHVQ2ZVf7_h6IXFcTf7nuT468OLJNEY9FQRJLBcc,105
+rusterize-0.2.0.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
+rusterize/__init__.py,sha256=OymrFdgWCN3VMuSM3oXoGKeagAd-5ayPsYyXnQ_HsDE,101
+rusterize/core.py,sha256=9nsqL-v5Bw5DezS_kpnDx1eQHooJr6zK1TpWSKxJT94,4574
+rusterize/rusterize.abi3.so,sha256=Q51iPEqNMkD9ifUI6tOWopqSxLXL4l122E-diJ1qEMk,33627216
+rusterize-0.2.0.dist-info/RECORD,,

{rusterize-0.1.0.dist-info → rusterize-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.8.1)
+Generator: maturin (1.8.3)
 Root-Is-Purelib: false
 Tag: cp310-abi3-macosx_10_12_x86_64

rusterize-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-rusterize-0.1.0.dist-info/METADATA,sha256=pS1UlizVrXEDCis4_jefaIP1bDrZH5lJGquhtWwM69g,7938
-rusterize-0.1.0.dist-info/WHEEL,sha256=o7axhT60SX08cKnffoNQ5wynMFwx6jcjMA-vg-8vXS0,105
-rusterize-0.1.0.dist-info/licenses/LICENSE,sha256=v-2DqBji_azGEWFDxBhw-CNIRu8450vBbloLx6UNqLU,1108
-rusterize/__init__.py,sha256=OymrFdgWCN3VMuSM3oXoGKeagAd-5ayPsYyXnQ_HsDE,101
-rusterize/core.py,sha256=eSBSQMebf3vELR6FHvmL7j-66mnWcRDXiow-flG5H8M,2861
-rusterize/rusterize.abi3.so,sha256=KjOv8BwV6Xs916FdPJxHMJMh3vleZ0yPPoM1594VUzk,33543688
-rusterize-0.1.0.dist-info/RECORD,,