API

Urban footprinter.

class urban_footprinter.UrbanFootprinter(raster, urban_classes=None, res=None, convolve_border_type=None, lulc_dtype=None, mask_dtype=None)

Urban footprinter.

compute_footprint_mask(kernel_radius, urban_threshold, num_patches=None, buffer_dist=None)

Compute a boolean mask of the urban footprint of a given raster.

Parameters:

kernel_radius (numeric) – The radius (in meters) of the circular kernel used in the convolution.
urban_threshold (float from 0 to 1) – Proportion of neighboring (within the kernel) urban pixels after which a given pixel is considered urban.
num_patches (int, default 1) – The number of urban patches that should be featured in the returned urban/non-urban mask. If a value lower than one is provided, the returned urban/non-urban mask will featuer all the urban patches. If no value is provided, the default value from settings.DEFAULT_NUM_PATCHES is used.
buffer_dist (numeric, optional) – Distance to be buffered around the urban/non-urban mask. If no value is provided, no buffer is applied.

Returns:

urban_mask

Return type:

ndarray

compute_footprint_mask_shp(kernel_radius, urban_threshold, num_patches=1, buffer_dist=None, transform=None)

Compute a geometry of the urban footprint of a given raster.

Parameters:

kernel_radius (numeric) – The radius (in meters) of the circular kernel used in the convolution.
urban_threshold (float from 0 to 1) – Proportion of neighboring (within the kernel) urban pixels after which a given pixel is considered urban.
num_patches (int, default 1) – The number of urban patches that should be featured in the returned urban/non-urban mask. If None or a value lower than one is provided, the returned urban/non-urban mask will featuer all the urban patches.
buffer_dist (numeric, optional) – Distance to be buffered around the urban/non-urban mask. If no value is provided, no buffer is applied.
transform (Affine, optional) – An affine transform matrix. Ignored if the instance was initialized with a path to a geotiff. If no transform is available, the geometry features will be generated based on pixel coordinates.

Returns:

urban_mask_geom

Return type:

GeometryCollection

get_convolution_result(kernel_radius)

Get the result of convolving the raster with the kernel.

Parameters:: kernel_radius (numeric) – The radius (in meters) of the circular kernel used in the convolution.
Returns:: convolution_result
Return type:: ndarray

urban_footprinter.urban_footprint_mask(raster, kernel_radius, urban_threshold, urban_classes=None, num_patches=1, buffer_dist=None, res=None)

Compute a boolean mask of the urban footprint of a given raster.

Parameters:

raster (ndarray or str, file object or pathlib.Path object) – Land use/land cover (LULC) raster. If passing a ndarray (instead of the path to a geotiff), the resolution (in meters) must be passed to the res keyword argument.
kernel_radius (numeric) – The radius (in meters) of the circular kernel used in the convolution.
urban_threshold (float from 0 to 1) – Proportion of neighboring (within the kernel) urban pixels after which a given pixel is considered urban.
urban_classes (int or list-like, optional) – Code or codes of the LULC classes that must be considered urban. Not needed if raster is already a boolean array of urban/non-urban LULC classes.
num_patches (int, default 1) – The number of urban patches that should be featured in the returned urban/non-urban mask. If None or a value lower than one is provided, the returned urban/non-urban mask will featuer all the urban patches.
buffer_dist (numeric, optional) – Distance to be buffered around the urban/non-urban mask. If no value is provided, no buffer is applied.
res (numeric, optional) – Resolution of the raster (assumes square pixels). Ignored if raster is a path to a geotiff.

Returns:

urban_mask

Return type:

ndarray

urban_footprinter.urban_footprint_mask_shp(raster, kernel_radius, urban_threshold, urban_classes=None, num_patches=1, buffer_dist=None)

Compute a geometry of the urban footprint of a given raster.

Parameters:

raster (str, file object or pathlib.Path object) – Path to the land use/land cover (LULC) raster.
kernel_radius (numeric) – The radius (in meters) of the circular kernel used in the convolution.
urban_threshold (float from 0 to 1) – Proportion of neighboring (within the kernel) urban pixels after which a given pixel is considered urban.
urban_classes (int or list-like, optional) – Code or codes of the LULC classes that must be considered urban. Not needed if raster is already a boolean array of urban/non-urban LULC classes.
num_patches (int, default 1) – The number of urban patches that should be featured in the returned urban/non-urban mask. If None or a value lower than one is provided, the returned urban/non-urban mask will featuer all the urban patches.
buffer_dist (numeric, optional) – Distance to be buffered around the urban/non-urban mask. If no value is provided, no buffer is applied.

Returns:

urban_mask_geom

Return type:

geometry