---
author: "Chris Reudenbach"
title: "Link GI to R"
date: "`r Sys.Date()`"
editor_options:
  chunk_output_type: console
output:
  html_document: 
    theme: united
    toc: true
  rmarkdown: default
  pdf_document:
    latex_engine: xelatex
    toc: true
urlcolor: blue
vignette: >
  %\VignetteIndexEntry{link2GI - Link GI to R}
  %\VignetteEncoding{UTF-8}{inputenc}\
  %\VignetteEngine{knitr::knitr}
---

# What is link2GI?

The [link2GI](https://CRAN.R-project.org/package=link2GI) package provides a lightweight linking framework that simplifies access to external GIS and remote-sensing software from R. Its primary purpose is to establish reliable connections to command-line interfaces of **GRASS GIS**, **SAGA GIS**, **Orfeo Toolbox (OTB)**, and **GDAL**, without requiring deep operating-system expertise.

The package emerged from repeated teaching scenarios in graduate-level GIS and remote-sensing courses, where students had to work on restrictive university Windows systems with limited privileges. In such environments, correctly configuring external GIS software often becomes the main obstacle—long before any actual spatial analysis can begin.

---

# Why link2GI?

R offers a rich ecosystem for handling spatial data. Vector data are primarily supported by [sp](https://CRAN.R-project.org/package=sp) and the more modern [sf](https://CRAN.R-project.org/package=sf) packages, while raster workflows are largely covered by [terra](https://CRAN.R-project.org/package=terra) and [stars](https://CRAN.R-project.org/package=stars). Specialized data formats, such as NetCDF, are well supported by packages like [ncdf4](https://CRAN.R-project.org/package=ncdf4).

Spatial analysis in R is often extended through wrapper packages that interface external libraries or command-line tools using R-like syntax, for example [geosphere](https://CRAN.R-project.org/package=geosphere), [Distance](https://CRAN.R-project.org/package=Distance), [igraph](https://CRAN.R-project.org/package=igraph), or [spatstat](https://CRAN.R-project.org/package=spatstat).

A comprehensive overview of this ecosystem is provided by *Geocomputation with R* (https://r.geocompx.org/), which serves as both an introduction and a reference for modern spatial data analysis in R.

Despite these strengths, a clear gap remains between R and mature open-source GIS and remote-sensing software. Systems such as **QGIS**, **GRASS GIS**, and **SAGA GIS** offer large collections of well-tested, efficient, and often highly optimized algorithms that are not fully replicated within R packages.

Bridging this gap is possible through wrapper packages. For **GRASS GIS (7/8)**, this role is filled by [rgrass](https://CRAN.R-project.org/package=rgrass). For **SAGA GIS**, [RSAGA](https://CRAN.R-project.org/package=RSAGA) and [Rsagacmd](https://github.com/stevenpawley/Rsagacmd) are available. However, for the **Orfeo Toolbox**, no mature, general-purpose R wrapper exists, despite its importance for large-scale remote-sensing workflows.

In practice, users frequently encounter substantial technical barriers related to operating systems, library dependencies, and software version mismatches. GRASS GIS, in particular, requires a carefully configured environment and a strictly defined spatial database structure. Setting up such an environment from R—especially on Windows systems—can be disproportionately complex when the goal is simply to run a single algorithm.

---

# What does “linking” mean?

In the context of *link2GI*, linking refers to the automated detection and configuration of all environment variables required to access external GIS software via their command-line APIs. The package does not reimplement GIS algorithms. Instead, it prepares a consistent execution environment so that existing tools can be used directly and reproducibly from R.

The package analyses available installations, identifies compatible versions, and establishes either temporary or permanent environments that comply with the requirements of the respective software. Where possible, *link2GI* integrates seamlessly with existing wrapper packages.

---

## GRASS GIS

GRASS GIS imposes the most stringent requirements. In addition to numerous environment variables, it requires a correctly defined spatial database, including projection, extent, and resolution. The `linkGRASS()` function searches for available GRASS installations, optionally allows interactive selection, and initializes a valid GRASS session.

Once initialized, users can access both the **rgrass** interface and the native GRASS command-line API within the same R session.

---

## SAGA GIS

SAGA GIS is comparatively easy to configure. The `linkSAGA()` function locates available installations, sets the required paths, and returns a configuration object that can be passed to wrapper packages such as **RSAGA**. Alternatively, users may directly call the `saga_cmd` command-line interface via R’s `system()` function.

---

## Orfeo Toolbox (OTB)

The Orfeo Toolbox is a powerful framework for remote-sensing tasks such as classification, filtering, and machine-learning-based image analysis. While selected OTB algorithms are available through R packages, these implementations are often limited to small datasets or are not designed for large-scale workflows.

*link2GI* identifies available OTB installations and exposes their command-line interfaces in a structured way. In the absence of a comprehensive R wrapper, the package provides a lightweight parser for OTB applications, enabling reproducible and scriptable execution of OTB modules from R.

---

## GDAL

Although GDAL functionality is widely accessible through R packages, direct access to GDAL binaries remains useful in several scenarios—particularly following the retirement of `rgdal` and related packages. Version differences between GDAL, PROJ, and Python environments can make it difficult to identify a compatible setup.

*link2GI* scans for available GDAL installations and returns structured information about their binaries and paths, enabling explicit and controlled use of GDAL command-line tools from R.


