# gdalraster 
[](https://github.com/firelab/gdalraster/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/ctoney/gdalraster)
[](https://github.com/firelab/gdalraster/actions/workflows/rhub.yaml)
[](https://CRAN.R-project.org/package=gdalraster)
[](https://firelab.r-universe.dev/gdalraster)
[](https://anaconda.org/conda-forge/r-gdalraster)
[](https://www.bestpractices.dev/projects/9382)
[](https://scorecard.dev/viewer/?uri=github.com/firelab/gdalraster)
## Overview
**gdalraster** is an R interface to the Raster and Vector
[APIs](https://gdal.org/en/stable/api/index.html) of the Geospatial Data
Abstraction Library ([GDAL](https://gdal.org/en/stable/)).
API bindings are implemented in the exposed C++ classes
[`GDALRaster`](https://firelab.github.io/gdalraster/reference/GDALRaster-class.html)
and
[`GDALVector`](https://firelab.github.io/gdalraster/reference/GDALVector-class.html),
along with several [stand-alone
functions](https://firelab.github.io/gdalraster/reference/index.html#stand-alone-functions).
Initial bindings are provided to the `gdal` command line interface (CLI)
algorithms added in GDAL 3.11. Bindings to the GDAL Virtual Systems
Interface ([VSI](https://gdal.org/en/stable/api/cpl.html#cpl-vsi-h)) are
also included to support file system operations on URLs, cloud storage
services, Zip/GZip/7z/RAR, and in-memory files, as well as regular file
systems. Calling signatures resemble the native C, C++ and Python APIs
provided by the GDAL project.
The package supports:
- [using GDAL’s new CLI
algorithms](https://firelab.github.io/gdalraster/articles/use-gdal-cli-from-r.html)
from R when built against GDAL \>= 3.11.3
- GDAL traditional utilities for
[raster](https://firelab.github.io/gdalraster/reference/index.html#raster-utilities)
and
[vector](https://firelab.github.io/gdalraster/reference/index.html#vector-utilities)
- manual creation of uninitialized raster and vector datasets
- vector layer creation and schema management
- read/set parameters and metadata for raster bands and vector layers
- low-level I/O
- build/read/set color tables and raster attribute tables
- virtual raster (VRT) for virtual cropping, resampling, kernel
filtering, mosaicing
- GDAL multidimensional raster
([`mdim_as_classic()`](https://firelab.github.io/gdalraster/reference/mdim_as_classic.html),
[`mdim_info()`](https://firelab.github.io/gdalraster/reference/mdim_info.html),
[`mdim_translate()`](https://firelab.github.io/gdalraster/reference/mdim_translate.html))
- GDAL facilities for [vector
geoprocessing](https://firelab.github.io/gdalraster/reference/ogr_proc.html)
- spatial reference systems and coordinate transformation (PROJ via GDAL
headers)
- [geometry
API](https://firelab.github.io/gdalraster/reference/index.html#geometry)
operating on raw vectors of WKB or WKT strings (GEOS via GDAL headers)
- [dataset
management](https://firelab.github.io/gdalraster/reference/index.html#general-data-management)
(inspect/copy files/rename/delete)
- create/append to Seek-Optimized ZIP
([SOZip](https://github.com/sozip/sozip-spec))
- VSI abstraction for [file system
operations](https://firelab.github.io/gdalraster/reference/index.html#virtual-file-systems)
on URLs, cloud storage, in-memory, etc.
- Standard C binary file I/O through VSI (class
[`VSIFile`](https://firelab.github.io/gdalraster/reference/VSIFile-class.html))
Additional functionality includes:
- class
[`RunningStats`](https://firelab.github.io/gdalraster/reference/RunningStats-class.html)
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`](https://firelab.github.io/gdalraster/reference/CmbTable-class.html)
identifies and counts unique combinations of integer values using a
hash table.
- [`combine()`](https://firelab.github.io/gdalraster/reference/combine.html)
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()`](https://firelab.github.io/gdalraster/reference/calc.html)
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 data, vector layers and WKB/WKT geometries
**gdalraster** may be useful in applications that need scalable,
low-level I/O, or prefer a direct GDAL API. Comprehensive
[documentation](#documentation) is provided in the package and online.
## Installation
### From CRAN
Install the released version from CRAN with:
``` r
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 conda-forge
[Conda-forge](https://github.com/conda-forge/r-gdalraster-feedstock)
provides pre-compiled binary packages that track CRAN releases, for the
following platforms:
[](https://anaconda.org/conda-forge/r-gdalraster)
To install **gdalraster** into a particular conda environment with
[conda](https://docs.conda.io/projects/conda/en/stable/), in the
activated environment:
conda install --channel conda-forge r-gdalraster
### From R-universe
[R-universe](https://firelab.r-universe.dev/gdalraster) provides
pre-compiled binary packages for Windows and macOS that track the
development version of **gdalraster**. New packages are built usually
within ~1 hour of the most recent commit in branch `main`.
``` r
# Install the development version from r-universe
install.packages("gdalraster", repos = c("https://firelab.r-universe.dev", "https://cran.r-project.org"))
```
### From source code
#### Linux
GDAL \>= 3.1.0 built with GEOS is required, but a more recent version is
recommended.
On Ubuntu, recent versions of geospatial libraries can be installed from
the [ubuntugis-unstable
PPA](https://launchpad.net/~ubuntugis/+archive/ubuntu/ubuntugis-unstable)
with the following commands. Note that libxml2 is required for the R
package **xml2** which is a dependency, so we go ahead and install it
here as well:
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt update
sudo apt install libgdal-dev libgeos-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](https://launchpad.net/~ubuntugis/+archive/ubuntu/ppa) could be used
instead.
Package **sf** provides helpful
[instructions](https://github.com/r-spatial/sf#linux) for installing the
geospatial libraries on other Linux distributions.
With the dependent libraries available on the system, install from CRAN:
``` r
install.packages("gdalraster")
```
Or install the development version from GitHub using package
[remotes](https://remotes.r-lib.org/):
``` r
remotes::install_github("firelab/gdalraster")
```
#### Windows
[RTools](https://cran.r-project.org/bin/windows/Rtools/) is needed to
install from source on Windows. RTools since version 4.2 includes GDAL
and all other dependent libraries that are needed to compile
**gdalraster**. Note that CRAN release periodic revisions to RTools that
often include updates to the libraries as new versions become available.
[Release
6768](https://cran.r-project.org/bin/windows/Rtools/rtools45/news.html)
of RTools 4.5 contains GDAL 3.12.1, GEOS 3.14.1 and PROJ 9.7.1.
With RTools installed:
``` r
# Install the development version from GitHub
remotes::install_github("firelab/gdalraster")
```
#### macOS
GDAL can be installed with Homebrew:
brew install gdal
then
``` r
# Install the development version from GitHub
remotes::install_github("firelab/gdalraster")
```
It is not recommended to mix source installations and installation of
macOS binaries from CRAN. Consider installing the development version
from R-universe instead.
### Docker
See (thanks to Michael Sumner):
docker pull ghcr.io/hypertidy/gdal-r-full:latest
## Documentation
- [Reference Manual](https://firelab.github.io/gdalraster/reference/)
- [Raster API
Tutorial](https://firelab.github.io/gdalraster/articles/raster-api-tutorial.html)
- [Vector API
Overview](https://firelab.github.io/gdalraster/articles/vector-api-overview.html)
- [Using `gdal` CLI algorithms from
R](https://firelab.github.io/gdalraster/articles/use-gdal-cli-from-r.html)
- [Raster Attribute
Tables](https://firelab.github.io/gdalraster/articles/raster-attribute-tables.html)
- [Raster
Display](https://firelab.github.io/gdalraster/articles/raster-display.html)
- [GDAL Block
Caching](https://firelab.github.io/gdalraster/articles/gdal-block-cache.html)
- [GDAL Config Quick
Ref](https://firelab.github.io/gdalraster/articles/gdal-config-quick-ref.html)
- [Using R and GDAL from
conda-forge](https://firelab.github.io/gdalraster/articles/r-and-gdal-in-conda.html)
- [Vector Read
Benchmarks](https://firelab.github.io/gdalraster/articles/vector-read-benchmarks.html)
------------------------------------------------------------------------
Logo designed by Sylvain Beorchia