---
output: github_document
---

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

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

# gdalraster <a href="https://firelab.github.io/gdalraster/"><img src="man/figures/logo.svg" align="right" height="139" alt="gdalraster website" /></a>

<!-- badges: start -->
[![R-CMD-check](https://github.com/firelab/gdalraster/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/firelab/gdalraster/actions/workflows/R-CMD-check.yaml)
[![codecov](https://codecov.io/gh/ctoney/gdalraster/branch/main/graph/badge.svg?token=MXIOPZQ2IU)](https://app.codecov.io/gh/ctoney/gdalraster)
[![R-hub](https://github.com/firelab/gdalraster/actions/workflows/rhub.yaml/badge.svg)](https://github.com/firelab/gdalraster/actions/workflows/rhub.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/gdalraster)](https://CRAN.R-project.org/package=gdalraster)
[![r-universe status](https://firelab.r-universe.dev/badges/gdalraster)](https://firelab.r-universe.dev/gdalraster)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/r-gdalraster)](https://anaconda.org/conda-forge/r-gdalraster)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9382/badge)](https://www.bestpractices.dev/projects/9382)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/firelab/gdalraster/badge)](https://scorecard.dev/viewer/?uri=github.com/firelab/gdalraster)
<!-- badges: end -->

## 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
* 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
* [raster utilities](https://firelab.github.io/gdalraster/reference/index.html#raster-utilities)
* 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))
* coordinate transformation
* spatial reference systems
* [geometry API](https://firelab.github.io/gdalraster/reference/index.html#geometry) operating on raw vectors of WKB or WKT strings
* [vector utilities](https://firelab.github.io/gdalraster/reference/index.html#vector-utilities)
* GDAL facilities for [vector geoprocessing](https://firelab.github.io/gdalraster/reference/ogr_proc.html)
* [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))
* abstraction of [file system operations](https://firelab.github.io/gdalraster/reference/index.html#virtual-file-systems) on URLs, cloud storage, in-memory files, 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, eval=FALSE}
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:

[![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/r-gdalraster.svg)](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, eval=FALSE}
# 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, eval=FALSE}
install.packages("gdalraster")
```

Or install the development version from GitHub using package [remotes](https://remotes.r-lib.org/):

```{r, eval=FALSE}
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, eval=FALSE}
# Install the development version from GitHub
remotes::install_github("firelab/gdalraster")
```

#### macOS

GDAL can be installed with Homebrew:

```
brew install gdal
```

then

```{r, eval=FALSE}
# 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 https://github.com/hypertidy/gdal-r-ci (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)
* [Vector Read Benchmarks](https://firelab.github.io/gdalraster/articles/vector-read-benchmarks.html)
