README.md

Urban footprinter

A reusable convolution-based approach to detect urban extents from raster datasets.

LULC	Convolution result	Computed urban extent

The approach is built upon the methods used in the Atlas of Urban Expansion. The main idea is that a pixel is considered part of the urban extent depending on the proportion of built-up pixels that surround it. See the notebook overview or this blog post for a more detailed description of the procedure.

Citation: Bosch M. 2020. "Urban footprinter: a convolution-based approach to detect urban extents from raster data". Available from https://github.com/martibosch/urban-footprinter. Accessed: DD Month YYYY.

An example BibTeX entry is:

@misc{bosch2020urban,
  title={Urban footprinter: a convolution-based approach to detect urban extents from raster data},
  author={Bosch, Mart\'{i}},
  year={2020},
  doi={10.5281/zenodo.3699310},
  howpublished={Available from \url{https://github.com/martibosch/urban-footprinter}. Accessed: DD Month YYYY},
}

Installation and usage

To install use pip:

$ pip install urban-footprinter

Then use it as:

import urban_footprinter as ufp

# Or use `ufp.urban_footprint_mask_shp` to obtain the urban extent as a
# shapely geometry
urban_mask = ufp.urban_footprint_mask(
    "path/to/raster.tif", kernel_radius, urban_threshold, urban_classes=urban_classes
)

where

help(ufp.urban_footprint_mask)

Help on function urban_footprint_mask in module urban_footprinter:

urban_footprint_mask(raster, kernel_radius, urban_threshold, urban_classes=None, num_patches=1,
                     buffer_dist=None, res=None)
    Computes 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 : ndarray