fasterize

High performance raster conversion for modern spatial data 🚀🌏▦

https://github.com/hypertidy/fasterize

Keywords

Keywords from Contributors

Repository

High performance raster conversion for modern spatial data 🚀🌏▦

README.Rmd

---
output: 
  github_document:
    html_preview: FALSE
---

```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  tidy = FALSE,
  error = FALSE,
  fig.width = 7,
  fig.height = 4.5,
  fig.path = 'vignettes/readme-',
  cache=FALSE)
```



# fasterize

Fast polygon-to-raster conversion, burn polygon shapes and/or values into pixels. 




  [![R-CMD-check](https://github.com/hypertidy/fasterize/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/hypertidy/fasterize/actions/workflows/R-CMD-check.yaml)
  [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)
[![MIT Licensed - Copyright 2016 EcoHealth Alliance](https://img.shields.io/badge/license-MIT-blue.svg)](https://badges.mit-license.org/)
[![CRAN status](https://www.r-pkg.org/badges/version/fasterize)](https://CRAN.R-project.org/package=fasterize)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/fasterize)](https://www.r-pkg.org/pkg/fasterize)
[![Codecov test coverage](https://codecov.io/gh/hypertidy/fasterize/graph/badge.svg)](https://app.codecov.io/gh/hypertidy/fasterize)

  

**fasterize** is a high-performance replacement for the `rasterize()` function
in the [**raster**](https://cran.r-project.org/package=raster) package.

Functionality is currently limited to rasterizing polygons in [**sf**](https://cran.r-project.org/package=sf)-type
data frames.

## Installation

Install the current version of **fasterize** from CRAN:

```{r eval = FALSE}
install.packages('fasterize')
```

Install the development version of **fasterize** with [**devtools**](https://cran.r-project.org/package=devtools):

```{r eval = FALSE}
devtools::install_github("hypertidy/fasterize")
```

**fasterize** uses [**Rcpp**](https://cran.r-project.org/package=Rcpp) and thus requires a compile toolchain to install from source.
Testing (and for normal use of sf objects) requires [**sf**](https://cran.r-project.org/package=sf), which requires GDAL, GEOS, and PROJ to be installed.

## Usage

The main function, `fasterize()`, takes the same inputs as `raster::rasterize()` but currently has fewer options and is 
is limited to rasterizing polygons.

A `raster()` and `plot()` methods for rasters are re-exported from the [raster package](https://cran.r-project.org/package=raster).


```{r example-1, message=FALSE}
library(raster)
library(fasterize)
library(wk)
library(fasterize)
p123 <- c(paste0("POLYGON ((-180 -20, -140 55, 10 0, -140 -60, -180 -20),", 
                  "(-150 -20, -100 -10, -110 20, -150 -20))"), 
             "POLYGON ((-10 0, 140 60, 160 0, 140 -55, -10 0))", 
             "POLYGON ((-125 0, 0 60, 40 5, 15 -45, -125 0))")
pols <- data.frame(value = seq_along(p123), geometry = wk::as_wkt(p123))
ex <- as.numeric(wk_bbox(pols))[c(1, 3, 2, 4)]
r <- raster::raster(raster::extent(ex), res = 1)
r <- fasterize(pols, r, field = "value", fun="sum")
plot(r)
```

## Performance

Let's compare `fasterize()` to  `terra::rasterize()`:

```{r benchmark, cache=TRUE}
pols_t <- terra::vect(p123)
pols_t$value <- 1:3
#pols_r <-  as(pols_t, "Spatial")
tr <- terra::rast(r)

bench <- microbenchmark::microbenchmark(
 # rasterize = r <- raster::rasterize(pols_r, r, field = "value", fun="sum"),
  terrarize = tr <- terra::rasterize(pols_t, tr, field = "value", fun = "sum"),
  fasterize = f <- fasterize(pols, r, field = "value", fun="sum"),
  unit = "ms"
)

print(bench, digits = 3)
```



How does `fasterize()` do on a large set of polygons? Here I download the IUCN shapefile for the ranges of all terrestrial mammals and generate
a 1/6 degree world map of mammalian biodiversity by rasterizing all the layers.


(this doesn't work anymore because the source data is gone, left as a record 2024-09-25). 

```{r download, eval=FALSE, cache=TRUE}
if(!dir.exists("Mammals_Terrestrial")) {
  download.file(
    "https://s3.amazonaws.com/hp3-shapefiles/Mammals_Terrestrial.zip",
    destfile = "Mammals_Terrestrial.zip") # <-- 383 MB
  unzip("Mammals_Terrestrial.zip", exdir = ".")
  unlink("Mammals_Terrestrial.zip")
}

```

```{r so-damn-fast, cache=FALSE, eval=FALSE}
mammal_shapes <- st_read("Mammals_Terrestrial")
mammal_raster <- raster(mammal_shapes, res = 1/6)
bench2 <- microbenchmark::microbenchmark(
  mammals = mammal_raster <- fasterize(mammal_shapes, mammal_raster, fun="sum"),
  times=20, unit = "s")
print(bench2, digits=3)
par(mar=c(0,0.5,0,0.5))
plot(mammal_raster, axes=FALSE, box=FALSE)
```


    #> Unit: seconds
    #>     expr   min    lq  mean median    uq   max neval
    #>  mammals 0.847 0.857 0.883  0.886 0.894 0.963    20



![](vignettes/readme-so-damn-fast-1.png)


## About

**fasterize** was developed openly at [EcoHealth Alliance](https://www.ecohealthalliance.org/) under the USAID PREDICT project by Noam Ross.   The repository for hosting fasterize was taken over by  Michael Sumner in December 2022, and was later migrated from Github 'ecohealthalliance/fasterize' to https://github.com/hypertidy/fasterize in March 2025. 


Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

[![https://www.ecohealthalliance.org/](vignettes/eha-footer.png)](https://www.ecohealthalliance.org/)
[![https://ohi.vetmed.ucdavis.edu/programs-projects/predict-project](vignettes/predictfooter.png)](https://ohi.vetmed.ucdavis.edu/programs-projects/predict-project)

Owner

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "fasterize",
  "description": "Provides a drop-in replacement for rasterize() from the 'raster' package that takes 'sf'-type objects, and is much faster. There is support for the main options provided by the rasterize() function, including setting the field used and background value, and options for aggregating multi-layer rasters. Uses the scan line algorithm attributed to Wylie et al. (1967) <doi:10.1145/1465611.1465619>.",
  "name": "fasterize: Fast Polygon to Raster Conversion ",
  "codeRepository": "https://github.com/hypertidy/fasterize",
  "issueTracker": "https://github.com/hypertidy/fasterize/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.0.4",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.2.1 (2022-06-23)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Noam",
      "familyName": "Ross",
      "email": "ross@ecohealthalliance.org",
      "@id": "https://orcid.org/0000-0002-2136-0000"
    }
  ],
  "author": [
    {
      "@type": "Person",
      "givenName": "Michael",
      "familyName": "Sumner",
      "email": "mdsumner@gmail.com",
      "@id": "https://orcid.org/0000-0002-2471-7511"
    },
    {
      "@type": "Person",
      "givenName": "Jeroen",
      "familyName": "Ooms"
    },
    {
      "@type": "Person",
      "givenName": "Antoine",
      "familyName": "Stevens"
    }
  ],
  "copyrightHolder": [
    {
      "@type": "Organization",
      "name": "EcoHealth Alliance"
    }
  ],
  "funder": [
    {
      "@type": "Organization",
      "name": "USAID PREDICT"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Michael",
      "familyName": "Sumner",
      "email": "mdsumner@gmail.com",
      "@id": "https://orcid.org/0000-0002-2471-7511"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "microbenchmark",
      "name": "microbenchmark",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=microbenchmark"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sf"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "spelling",
      "name": "spelling",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spelling"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.3.0"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "methods",
      "name": "methods"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "Rcpp",
      "name": "Rcpp",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Rcpp"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "raster",
      "name": "raster",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=raster"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "sp",
      "name": "sp",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sp"
    },
    "SystemRequirements": "C++11"
  },
  "fileSize": "19162.002KB"
}

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 4 months ago