README.Rmd

---
output:
  github_document:
    html_preview: false
---

```{r setup, include = FALSE}
  knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/REAsDME-",
  out.width = "100%"
)
```

<!-- README.md is generated from README.Rmd. Please edit that file -->

# foot: An R package for processing building footprints
*[WorldPop Research Group, University of Southampton](https://www.worldpop.org/)*

While remote sensing has long been used to monitor urbanisation patterns, in
recent years there has been an increasing availability in finer resolution
satellite data covering large areas of the globe. This very high resolution
imagery (often <1 m spatial resolution), combined with increased computing power
is producing new datasets on urban areas. In particular, machine learning
algorithms are being applied to detect, automatically extract, and map full sets
of building features in a scene. These automated methods add to the manually
digitised information such as from [OpenStreetMap](http://www.openstreetmap.org)
and the property datasets available from some city governments.

Such building footprint datasets provide a new level of detail on urban areas,
particularly in places which might otherwise lack detailed maps on cities and
rapidly growing areas. Despite their spatial detail, building footprints
typically lack any other attribute information to help differentiate land uses
or other neighbourhood characteristics. However, the size, shape, orientation,
and clustering of structures produces a spatial pattern that can suggest areas
of different land use or activities.

The `foot` package is designed to provide a set of consistent and flexible tools
for processing 2D vector representations of buildings and calculating urban
morphology measurements. The functionality includes basic geometry and
morphology measures, distance and clustering metrics. These calculations are
supported with helper functions for spatial intersections and tiled
reading/writing of data.

## Installation

The `foot` package can be installed directly from Github.
```r
devtools::install_github("wpgp/foot", build_vignettes = TRUE)
```

Note that building and running the code may require additional packages:
`stars`, `raster`, `sf`, `data.table`, `lwgeom`, `mmap`. et al.

## Quick Start

A sample dataset of building footprints is provided: 
```
# load the sample
data("kampala", package="foot")

# 2D vector building polygons
kampala$buildings
```

### Vignettes

Vignettes are provided as an introduction to `foot`. The vignette on basic usage
is available from `vignette("footsteps", package = "foot")`. The supplied
datasets can be used to replicate this vignette. For a discussion and example of
creating gridded data layers, see `vignette("bigfoot", package = "foot")`.
Finally, techniques for using custom morphology metric functions with `foot` is
demonstrated in `vignette("cobbler", package = "foot")`. These vignettes are
also available from this package website.

### Basic Usage

```{r, message=FALSE, warning=FALSE}
library(foot)

# load sample data
data("kampala", package = "foot")
buildings <- kampala$buildings
zones <- kampala$adminZones
grid <- kampala$mastergrid
```

The `foot` package provides tools to calculate and summarise building morphology
measures at multiple scales. These include building-level geometry measures.
```{r message=FALSE, warning=FALSE, tidy=FALSE}
# building-level metrics
buildings$built_area <- calculate_footstats(buildings, what = "area")
  head(buildings)
```

As well as area-level summaries within spatial zones.
```{r, message=FALSE, warning=FALSE, tidy=FALSE}
# Area-level summary metrics
# Optionally, create an index for the buildings to zones
building_zone <- zonalIndex(buildings, 
                            zones, 
                            zoneField = "Id", 
                            returnObject = TRUE)

# summarise metrics within small areal units
admin_area <- calculate_footstats(building_zone, 
                                  zone = "Id", 
                                  what = "area", how = "mean")
  head(admin_area)
```

Or gridded summary outputs, with the options to include a circular focal window.
```{r message=FALSE, warning=FALSE, tidy=FALSE}
# calculated along a raster within a circular focal window
gridded <- calculate_bigfoot(buildings, 
                             what = "area", 
                             how = "mean",
                             focalRadius = 200,
                             template = grid,
                             outputPath = tempdir())

  raster::plot(raster::raster(gridded))
  plot(sf::st_geometry(buildings), add = TRUE)
```

### Outputs

Rasters in GeoTiff format or data tables:  
  
1. Binary settlement indicators
2. Counts of structures
3. Building area 
4. Building perimeter 
5. Nearest neighbour distance 
6. Nearest neighbour index
7. Structure orientation angle (normalised entropy)
8. Compactness (Polsby-Popper) 
9. Roundness
10. Length to (equivalent-) width ratio

A full list of characteristics and summary function names can be retrieved with
`foot::list_fs()`.

## Contributions

Contributions are welcome. Raise or respond to an issue, or create a new branch
to develop a feature/modification and submit a pull request.


## Acknowledgements

```{r}
citation("foot")
```

This work was undertaken by members of the WorldPop Research Group at the
University of Southampton (Chris Jochem, Edith Darín, Claire Dooley, Doug
Leasure) with support from Andy Tatem and Attila Lazar. Funding support comes
from the Bill and Melinda Gates Foundation and the United Kingdom Foreign,
Commonwealth & Development Office as part of the Geo-Referenced Infrastructure
and Demographic Data for Development project (GRID3) (OPP1182408). Project
partners in [GRID3](https://grid3.org/) include the WorldPop Research Group, the
United Nations Population Fund, the Flowminder Foundation, and the Center for
International Earth Science Information Network within the Earth Institute at
Columbia University.