rasterstats

Common errors

• Error - Rasterize Geom - Width and Height must be > 0

  cause The vector geometry does not sufficiently overlap with the raster, or the rasterization process results in a zero-sized internal raster representation for that geometry. This is often due to very small polygons, CRS mismatch, or invalid geometries.
  fix Verify CRS alignment between vector and raster. Remove or repair invalid/empty geometries. For small polygons, try `zonal_stats(..., all_touched=True)` or ensure polygons are large enough to cover at least one raster cell centroid.

• AttributeError: 'NoneType' object has no attribute 'crs' (or similar errors related to 'NoneType' geometries)

  cause The input vector data contains null, empty, or otherwise invalid geometries that `rasterstats` attempts to process, leading to an unexpected `None` value.
  fix Filter out invalid or empty geometries from your vector dataset before passing it to `rasterstats`. For example, when using GeoPandas: `gdf = gdf[~(gdf['geometry'].is_empty | gdf['geometry'].isna())]`.

• Depreciated dependency on python 3.12 (numpy.distutils) causes error on import

  cause This appears to be a recent, open issue related to `numpy.distutils` being deprecated in Python 3.12 and causing import errors with `rasterstats` in some environments.
  fix As of current knowledge, this is an active issue in some setups with Python 3.12. Consider using Python 3.9, 3.10, or 3.11, or check the `rasterstats` GitHub issues for a resolution or workaround from the maintainers.

Warnings

• breaking Python 2 support was dropped in version 0.19.0. Additionally, Python 3.8 support was dropped in version 0.20.0. The minimum required Python version is now 3.9.
  Fix: Upgrade your Python environment to 3.9 or newer before upgrading rasterstats to versions 0.19.0+.
• gotcha The `all_touched` parameter (default `False`) in `zonal_stats` can significantly impact results. With `all_touched=False`, only pixels whose centroids intersect a vector geometry are included. This may result in `None` statistics for very small polygons. Setting `all_touched=True` includes all pixels touched by the geometry, which can potentially bias results by including edge pixels not fully representative of the geometry.
  Fix: Understand the implications of `all_touched`. For small polygons, consider `all_touched=True` or pre-processing to ensure intersection. Always validate results, especially if polygon sizes vary greatly relative to raster pixel size.
• gotcha Encountering 'Width and Height must be > 0' errors or `NoneType` attribute errors often indicates issues with the spatial intersection between your vector geometries and the raster data. This can be caused by misaligned Coordinate Reference Systems (CRS), empty or invalid geometries in the vector layer, or geometries being too small to intersect any raster cells under the default `all_touched=False` setting.
  Fix: Ensure vector and raster data share the same CRS. Filter out any null or empty geometries from your vector dataset. If polygons are very small, try `all_touched=True` in `zonal_stats` or increase the polygon size slightly for testing. Verify affine transformation for manually created rasters.
• gotcha Processing very large rasters with complex MultiPolygon geometries (especially if spread out over vast areas) can lead to excessive memory consumption, potentially crashing the process. This is because `rasterstats` may attempt to read large sections of the raster into memory for processing.
  Fix: Consider splitting large MultiPolygon features into individual polygons or smaller subsets. For extremely large datasets, external tools or custom C++ solutions might be more memory efficient. Alternatively, ensure sufficient RAM is available or process data in chunks.
• deprecated Older versions of `rasterstats` (e.g., 0.14.0-0.16.0) issued deprecation warnings when used with newer versions of `shapely` (1.8+), `Affine`, and `numpy` (v1.16+).
  Fix: Upgrade `rasterstats` to version 0.17.0 or newer to ensure compatibility with recent versions of its core dependencies and suppress these warnings.

Install

• pip install rasterstats Install with pip

Imports

• zonal_stats

  from rasterstats import zonal_stats

• point_query

  from rasterstats import point_query

Quickstart

Demonstrates how to use `zonal_stats` to calculate summary statistics for raster data based on vector geometries (e.g., polygons) and `point_query` to retrieve raster values at specific point locations. The example placeholders for file paths need to be replaced with actual geospatial data.

import os
from rasterstats import zonal_stats, point_query

# This is a simplified example. In a real scenario, you'd load actual geospatial files.
# For demonstration, we'll simulate inputs or refer to a common pattern.
# Assuming 'polygons.shp' and 'elevation.tif' exist in a 'data' directory for this example.
# You would replace these paths with your actual data file paths.

# Example for zonal_stats
# stats = zonal_stats(os.environ.get('VECTOR_PATH', 'data/polygons.shp'), 
#                     os.environ.get('RASTER_PATH', 'data/elevation.tif'), 
#                     stats=['min', 'max', 'mean', 'median'])
# print('Zonal Stats for first polygon:', stats[0])

# Example for point_query
# point_geom = {'type': 'Point', 'coordinates': (245309.0, 1000064.0)} # Example coordinate
# value = point_query(point_geom, os.environ.get('RASTER_PATH', 'data/elevation.tif'))
# print('Point Query value:', value)

print("To run quickstart, ensure you have 'polygons.shp' and 'elevation.tif' files.")
print("Uncomment the examples in the code to execute them.")
print("For full quickstart, refer to the official documentation.")