raster_tools.Vector.to_raster#

Vector.to_raster(like, field=None, overlap_resolve_method='last', mask=False, mask_invert=False, null_value=None, all_touched=True, use_spatial_aware=False, show_progress=False)[source]#

Convert vector feature data to a raster.

This method can be used to either rasterize features using values from a particular data field or to create a raster mask of zeros and ones. Using values to rasterize is the default. Use mask=True to generate a raster mask. If no data field is specified, the underlying dataframe’s index is used. NOTE: because of limitations in dask, dataframe index values are not guaranteed to be unique across the dataframe. Cells that do not touch or overlap any features are marked as null.

To add a column of unique IDs for each feature, see raster_tools.vector.add_objectid_column() or raster_tools.vector.Vector.add_objectid_column().

This operation can be greatly accelerated if the provided features object has been spatially shuffled or had spatial partitions calculated. There are a few ways to do this. For Vector or GeoDataFrame/GeoSeries objects, you can use the spatial_shuffle or calculate_spatial_partitions methods. calculate_spatial_partitions simply computes the spatial bounds of each partition in the data. spatial_shuffle shuffles the data into partitions of spatially near groups and calculates the spatial bounds at the same time. This second method is more expensive but provides a potentially greater speed up for rasterization. The use_spatial_aware flag can also be provided to this function. This causes the spatial partitions to be calculated before rasterization.

Note

If the CRS for this vector does not match the CRS for like, this vector will be transformed to like’s CRS. This operation causes spatial partition information to be lost. It is recommended that the CRSs for both are matched ahead of time.

Parameters

  • like (Raster) – A raster to use for grid and CRS information. The resulting raster will be on the same grid as like.

  • field (str, optional) – The name of a field to use for cell values when rasterizing the vector features. If None or not specified, the underlying dataframe’s index is used. The default is to use the index.

  • overlap_resolve_method (str, optional) –

    The method used to resolve overlaping features. Default is “last”. The available methods are:

    ’first’

    Cells with overlapping features will receive the value from the feature that appears first in the feature table.

    ’last’

    Cells with overlapping features will receive the value from the feature that appears last in the feature table.

    ’min’

    Cells with overlap will receive the value from the feature with the smallest value.

    ’max’

    Cells with overlap will receive the value from the feature with the largest value.

  • mask (bool, optional) – If True, the features are rasterized as a mask. Cells that do not touch a feature are masked out. Cells that touch the features are set to 1. If mask_invert is also True, this is inverted. If mask is False, the features are rasterized using field to retrieve values from the underlying dataframe. field is ignored, if this option is a used. Default is False.

  • mask_invert (bool, optional) – If True cells that are inside or touch a feature are masked out. If False, cells that do not touch a feature are masked out. Default is False.

  • null_value (scalar, optional) – The value to use in cells with no feature data, when not masking.

  • all_touched (bool, optional) – If True, grid cells that the vector touches will be burned in. If False, only cells with a center point inside of the vector perimeter will be burned in.

  • use_spatial_aware (bool, optional) – Force the use of spatial aware rasterization. If True and features is not already spatially indexed, a spatial index will be computed. Alternatively, if True and features’s CRS differs from like, a new spatial index in a common CRS will be computed. If features already has a spatial index and its CRS matches like, this argument is ignored. Default is False.

  • show_progress (bool, optional) – If use_spatial_aware is True, this flag causes a progress bar to be displayed for spatial indexing. Default is False.

Returns

The resulting single band raster of rasterized features. This raster will be on the same grid as like.

Return type

Raster