Skip to contents

gdalraster

Overview

gdalraster is an R interface to the Raster API of the Geospatial Data Abstraction Library (GDAL). Bindings to a subset of the GDAL Virtual Systems Interface (VSI) are also provided to support filesystem operations on URLs, cloud storage services, Zip/GZip/7z/RAR, and in-memory files. Calling signatures resemble the native C, C++ and Python APIs provided by the GDAL project.

Bindings to GDAL are implemented in the exposed C++ class GDALRaster along with several stand-alone functions, supporting:

  • manual creation of uninitialized raster datasets
  • creation from existing raster as template
  • read/set raster dataset parameters
  • low-level I/O
  • build/read/set color tables and raster attribute tables
  • virtual raster (VRT) for virtual cropping, resampling, kernel filtering, mosaicing
  • gdalwarp wrapper for reproject/resample/crop/mosaic
  • coordinate transformation
  • spatial reference systems
  • GDAL algorithms (dem_proc(), polygonize(), rasterize(), ...)
  • OGR vector utilities (ogrinfo(), ogr2ogr())
  • copy files/move/rename/delete datasets
  • abstraction of filesystem operations on URLs and cloud storage
  • create/append to Seek-Optimized ZIP (SOZip)

Additional functionality includes:

  • class RunningStats calculates mean and variance in one pass, and tracks the min, max, sum, and count (i.e., summary statistics on a data stream). The input data values are not stored in memory, so this class can be used to compute statistics for very large data streams.
  • class CmbTable identifies and counts unique combinations of integer values using a hash table.
  • combine() overlays multiple rasters so that a unique ID is assigned to each unique combination of input values. Pixel counts for each unique combination are obtained, and combination IDs are optionally written to an output raster.
  • calc() evaluates an R expression for each pixel in a raster layer or stack of layers. Individual pixel coordinates are available as variables in the R expression, as either x/y in the raster projected coordinate system or inverse projected longitude/latitude.
  • plot_raster() displays raster data using base R graphics.

gdalraster may be useful in applications that need scalable, low-level I/O, or prefer a direct GDAL API. Comprehensive documentation is provided in the package and online.

Installation

Install the released version from CRAN with:

install.packages("gdalraster")

CRAN provides pre-compiled binary packages for Windows and macOS. These do not require any separate installation of external libraries for GDAL.

From source code

Linux

GDAL >= 3.1.0 is required, but a more recent version is recommended (e.g., >= 3.6.4). GDAL built with GEOS is a system requirement as of gdalraster 1.10. GDAL as of 3.9 requires PROJ >= 6.3.1, but a more recent version of PROJ is recommended. PROJ requires sqlite3, and libxml2 is required for the imported R package xml2.

On Ubuntu, recent versions of geospatial libraries can be installed from the ubuntugis-unstable PPA with the following commands:

sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt update
sudo apt install libgdal-dev libgeos-dev libproj-dev libsqlite3-dev libxml2-dev

The versions in ubuntugis-unstable generally work well and are more up-to-date, but less recent versions in the ubuntugis-stable PPA could be used instead.

Package sf provides helpful instructions for installing the geospatial libraries on other Linux distributions.

With the dependent libraries available on the system, install from CRAN:

install.packages("gdalraster")

Or install the development version from GitHub using package remotes:

remotes::install_github("USDAForestService/gdalraster")

Windows

RTools is needed to install from source on Windows. RTools since version 4.2 includes GDAL, PROJ and all other dependent libraries that are needed to compile gdalraster. Note that CRAN releases periodic revisions to RTools that often include updates to the libraries as new versions become available. For example, revision 5958 of RTools 4.3 contains GDAL 3.8.2 and PROJ 9.3.1.

With RTools installed:

# Install the development version from GitHub
remotes::install_github("USDAForestService/gdalraster")

macOS

GDAL and PROJ can be installed with Homebrew:

brew install pkg-config gdal proj

Then configure.args is needed:

# Install the development version from GitHub
remotes::install_github("USDAForestService/gdalraster", configure.args = "--with-proj-lib=$(brew --prefix)/lib/")

Documentation