Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hypertidy/vapour

GDAL API package for R
https://github.com/hypertidy/vapour

cpp gdal gdal-api

Last synced: about 2 months ago
JSON representation

GDAL API package for R

Awesome Lists containing this project

README 

        
---

output: github_document

---



 

```{r setup, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)



```



# vapour  



[![R_build_status](https://github.com/hypertidy/vapour/workflows/R-CMD-check/badge.svg)](https://github.com/hypertidy/vapour/actions)

[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/vapour)](https://cran.r-project.org/package=vapour)

[![CRAN status](https://www.r-pkg.org/badges/version/vapour)](https://CRAN.R-project.org/package=vapour)



## Overview



The vapour package provides access to the basic *read* functions available in [GDAL](https://gdal.org/) for both [raster](https://gdal.org/user/raster_data_model.html) and [vector](https://gdal.org/user/vector_data_model.html) data sources. 



The functions are deliberately *lower-level* than these data models and provide access to the

component entities independently. 



For vector data: 



* read access to fields alone

* read raw binary geometry alone, or geometry in text forms (GeoJSON, WKT, GML, KML).

* read access to the extent of geometries

* helper functions to summarize feature identity and geometry status

* limit/skip control on records read 

* execution of [OGRSQL](https://gdal.org/user/ogr_sql_dialect.html) with control of SQL dialect

* read in the context of a [bounding box spatial filter](https://gdal.org/user/ogr_sql_dialect.html#executesql) can be applied via the `extent` argument

 



For raster data: 



* read access to the list of available rasters within a collection source (subdatasets). 

* read access to *structural metadata* for individual raster sources. 

* read access for raw data using GDAL's  [RasterIO framework](https://gdal.org/tutorials/raster_api_tut.html) and its dynamic image decimation / replication resampling algorithms. 

* read access for raw data using GDAL's [Warper framework](https://gdal.org/api/gdalwarp_cpp.html) and its dynamic image warping, a superset of the RasterIO capabilities. 



The warper works for data sources that contain *overviews* (or pyramid levels-of-detail) as it automatically chooses an appropriate level for the request made, files, urls, database connections, online tiled image servers, and all the various ways of specifying GDAL data sources. 



The workflows available are intended to support development of applications in R for these vector and [raster data](https://en.wikipedia.org/wiki/Raster_data) without being constrained to any particular data model. 



## Installation



Install from CRAN, this should work on MacOS and Windows because CRAN provide binaries. 



```{r, install-cran,eval=FALSE}

install.packages("vapour")

```



The development version can be installed from Github. 



```{r install-universe, eval=FALSE}

options(repos = c(

    hypertidy = 'https://hypertidy.r-universe.dev',

    CRAN = 'https://cloud.r-project.org'))

install.packages("vapour")

```



To install the development version the more github-traditional way: 



```{r install-dev, eval=FALSE}

remotes::install_github("hypertidy/vapour")

```



You will need development tools for building R packages. 



On Linux, I'm using latest ubuntu and R usually, check CRAN on ubuntu (search for "ubuntu cran"). 



then



```bash

apt install --no-install-recommends software-properties-common dirmngr

add-apt-repository ppa:ubuntugis/ubuntugis-unstable --yes



apt update



## Install 3rd parties



## NetCDF and geo-spatial wunderkind

apt install libgdal-dev 



```



then `install.packages("vapour")` or whatever you use. 



## Purpose 



The goal of vapour is to provide a basic **GDAL API** package for R. The key functions provide vector geometry or attributes and raster data and raster metadata. 



The priority is to give low-level access to key functionality rather than

comprehensive coverage of the library. The real advantage of `vapour` is the

flexibility of a modular workflow, not the outright efficiency.



A parallel goal is to be freed from the powerful but sometimes limiting

high-level data models of GDAL itself, specifically these are *simple features*

and *affine-based regular rasters composed of 2D slices*. (GDAL will possibly

remove these limitations over time but still there will always be value in

having modularity in an ecosystem of tools.)



GDAL's dynamic resampling of arbitrary raster windows is also very useful

for interactive tools on local data, and is radically under-utilized. A quick example, topography data is available from Amazon

compute servers, first we need a config for the source: 



```{r config-file}

elevation.tiles.prod <- 

 '

  

    https://s3.amazonaws.com/elevation-tiles-prod/geotiff/${z}/${x}/${y}.tif

  

  

    -20037508.34

    20037508.34

    20037508.34

    -20037508.34

    14

    1

    1

    top

  

  EPSG:3857

  512

  512

  1

  Int16

  403,404

  

    -32768

  

  

'



```

```{r topo-example}

## we want an extent

ex <- c(-1, 1, -1, 1) * 5000  ## 10km wide/high region

## Madrid is at this location

pt <- cbind(-3.716667, 40.416667)

crs <- sprintf("+proj=laea +lon_0=%f +lat_0=%f +datum=WGS84", pt[1,1,drop = TRUE], pt[1,2, drop = TRUE])

dm <- c(256, 256)



vals <- vapour::vapour_warp_raster(elevation.tiles.prod, extent = ex, dimension = dm, projection = crs)

## now we can use this in a matrix

image(m <- matrix(vals[[1]], nrow = dm[2], ncol = dm[1])[,dm[2]:1 ])

## using the image list format

x <- list(x = seq(ex[1], ex[2], length.out = dm[1] + 1), y = seq(ex[3] ,ex[4], length.out = dm[1] + 1), z = m)

image(x)



## or as a spatial object

library(terra)

r <- rast(ext(ex), nrows = dm[2], ncols = dm[1], crs = crs, vals = vals[[1]])

contour(r, add = TRUE)



```



If we want more detail, go ahead: 



```{r lod}

dm <- c(512, 512)

vals <- vapour::vapour_warp_raster(elevation.tiles.prod, extent = ex, dimension = dm, projection = crs)

(r <- rast(ext(ex), nrows = dm[2], ncols = dm[1], crs = crs, vals = vals[[1]]))

plot(r, col = hcl.colors(24))



```



GDAL is obstinately *format agnostic*, the A stands for *Abstraction* and we like that in R too, just gives us the data. Here we created a base matrix image object, and a raster package *RasterLayer*, but we could use the spatstat im, or objects in stars or terra packages, it makes no difference to the read-through-warp process. 



This partly draws on work done in [the sf package](https://github.com/r-spatial/sf) and [the terra package](https://github.com/rspatial/terra) and in packages `rgdal` and `rgdal2`.

I'm amazed that something as powerful and general as GDAL is still only

available through these lenses, but maybe more folks will get interested over time. 



## Examples



The package documentation page gives an overview of available functions. 



```R

help("vapour-package")

```



See the vignettes and documentation for examples WIP. 



## Context



Examples of packages that use vapour are in development, especially [whatarelief](https://github.com/hypertidy/whatarelief) and [ggdal](https://github.com/rgdal-dev/ggdal). 



Limitations, work-in-progress and other discussion: 



https://github.com/hypertidy/vapour/issues/4



We've kept a record of a minimal GDAL wrapper package here: 



https://github.com/diminutive/gdalmin



# Code of conduct



Please note that this project is released with a [Contributor Code of

Conduct](https://github.com/hypertidy/vapour/blob/master/CONDUCT.md). By participating in this project you agree to abide by its

terms.