qgisprocess

R package to use QGIS processing algorithms

https://github.com/r-spatial/qgisprocess

Repository

R package to use QGIS processing algorithms

README.Rmd

---
output: github_document
---



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

# qgisprocess




[![CRAN status](https://www.r-pkg.org/badges/version/qgisprocess)](https://CRAN.R-project.org/package=qgisprocess)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8260794.svg)](https://doi.org/10.5281/zenodo.8260794)
[![R-CMD-check](https://github.com/r-spatial/qgisprocess/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-spatial/qgisprocess/actions/workflows/R-CMD-check.yaml)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Codecov test coverage](https://codecov.io/gh/r-spatial/qgisprocess/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-spatial/qgisprocess/tree/main)


The goal of **qgisprocess** is to provide an R interface to the geoprocessing algorithms of [QGIS](https://qgis.org), a popular and open source desktop geographic information system (GIS) program.
The package is a re-implementation of functionality provided by the archived [RQGIS](https://cran.r-project.org/package=RQGIS) package, which was partially revived in the [RQGIS3](https://github.com/r-spatial/RQGIS3) package.

## Installation

### qgisprocess

To install the latest CRAN release, just run:

```{r eval=FALSE}
install.packages("qgisprocess")
```

You can install the development version from GitHub with:

```{r eval=FALSE}
# install.packages("remotes")
remotes::install_github("r-spatial/qgisprocess")
```

### QGIS

The **qgisprocess** package wraps the [standalone `qgis_process` command-line utility](https://docs.qgis.org/latest/en/docs/user_manual/processing/standalone.html), which is available in QGIS >= 3.16.

The package is meant to support _current_ QGIS releases, i.e. both the latest and the long-term release.
Although older QGIS releases are not officially supported, it may work since QGIS 3.16.
Installation instructions for all platforms are available at .

If a recent version of QGIS isn't available for your OS, you can use the [Geocomputation with R Docker image](https://github.com/geocompx/docker/pkgs/container/docker) with QGIS installed (`docker pull ghcr.io/geocompx/docker:qgis`).
See the vignette on 'getting started' for more information.

### Package configuration

If the automatic configuration fails (or if you have more than one QGIS installation and would like to choose which one is used), you can set `options(qgisprocess.path = "path/to/qgis_process")`.
Specify the `qgisprocess.path` option in your `.Rprofile`, to make your choices persistent between sessions.
You can run `qgis_configure()` to reconfigure the package, or just `qgis_configure(use_cached_data = TRUE)` to see the gritty details!

```{r}
library(qgisprocess)
```

## Functionality

Most functions start with the `qgis_` prefix, so that functions can be found more easily using tab completion.

The main function is `qgis_run_algorithm(algorithm = , ...)`.
It specifies the geoprocessing algorithm to be called with a `"provider:algorithm"` formatted identifier, e.g. `"native:convexhull"` or `"gdal:hillshade"`, and it passes the algorithm arguments as R function arguments.

Additional functions are provided to discover available geoprocessing algorithms, retrieve their documentation, handle processing results, manage QGIS plugins, and more.

Spatial layers can be passed to `qgis_run_algorithm()` as file paths but also as [sf](https://r-spatial.github.io/sf/), [stars](https://r-spatial.github.io/stars/), [terra](https://rspatial.github.io/terra/) or [raster](https://cran.r-project.org/package=raster) objects.

A structured overview of functions is available at .
To get started, read the 'getting started' vignette and use the [cheat sheets](https://r-spatial.github.io/qgisprocess/articles/)!

Note that R package [**qgis**](https://github.com/JanCaha/r_package_qgis) extends on **qgisprocess** by providing a separate R function for each geoprocessing algorithm.
In addition, it makes the QGIS algorithm documentation available in the corresponding R function documentation.

### Example

The following example demonstrates the [buffer](https://docs.qgis.org/latest/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html#buffer) algorithm in action.

```{r buffer, out.width='60%'}
input <- sf::read_sf(system.file("shape/nc.shp", package = "sf"))

result <- qgis_run_algorithm(
  "native:buffer",
  INPUT = input,
  DISTANCE = 1,
  DISSOLVE = TRUE
)

result

output_sf <- sf::st_as_sf(result)
plot(sf::st_geometry(output_sf))
```

### Some tips

You can search for algorithms with `qgis_search_algorithms()` (string matching with regex).

```{r}
qgis_search_algorithms(algorithm = "buffer", group = "[Vv]ector")
```

You can read the help associated with an algorithm using `qgis_show_help()`.

```{r eval=FALSE}
qgis_show_help("native:buffer")
```

A full list of available algorithms is returned by `qgis_algorithms()`.

```{r}
qgis_algorithms()
```

It may also be useful to run an algorithm in the QGIS GUI to determine how the various input values are translated to string processing arguments.
This can be done using the 'Advanced' dropdown, by copying either the `qgis_process` command string or the JSON string:

![](man/figures/copy_as_json.png)

Note that the JSON string can be passed directly to `qgis_run_algorithm()`!

## Code of Conduct

Please note that the qgisprocess project is released with a [Contributor Code of Conduct](https://r-spatial.github.io/qgisprocess/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.

## More information

### Presentations

- useR! 2024: [slides](https://florisvdh.github.io/user-2024-qgisprocess/)
- FOSS4G 2023: [slides](https://florisvdh.github.io/foss4g-2023-qgisprocess/) & [video](https://www.youtube.com/watch?v=Qt5DzWThWqI)
- FOSS4G 2021: [slides](https://dewey.dunnington.ca/slides/qgisprocess2021/) & [video](https://www.youtube.com/watch?v=iA0OQ2Icn6Y&t=1912s)

### In the wild

(Draft)

Following case studies have used the package:

- \. Source code: \.

_If you used the package in your work and would like to see it referenced here, then give a shout in issue [#211](https://github.com/r-spatial/qgisprocess/issues/211) or make a pull request!_

### Further reading

- A [paper](https://journal.r-project.org/archive/2017/RJ-2017-067/index.html) on the original RQGIS package published in the R Journal
- A [discussion](https://github.com/r-spatial/discuss/issues/41) about options for running QGIS from R that led to this package
- The [pull request](https://github.com/qgis/QGIS/pull/34617) in the QGIS repo that led to the development of the `qgis_process` command-line utility

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: If you use this software, please cite it using these metadata.
title: "R package qgisprocess: use QGIS processing algorithms"
authors:
- given-names: Dewey
  family-names: Dunnington
  affiliation: Voltron Data
  orcid: 0000-0002-9415-4582
- given-names: Floris
  family-names: Vanderhaeghe
  affiliation: Research Institute for Nature and Forest (INBO)
  orcid: 0000-0002-6378-6229
- given-names: Jan
  family-names: Caha
  orcid: 0000-0003-0165-0606
- given-names: Jannes
  family-names: Muenchow
  orcid: 0000-0001-7834-4717
keywords:
- R
- package
- QGIS
contact:
- given-names: Floris
  family-names: Vanderhaeghe
  affiliation: Research Institute for Nature and Forest (INBO)
  orcid: 0000-0002-6378-6229
doi: ~
license: GPL-3.0-or-later
repository-code: https://github.com/r-spatial/qgisprocess/
type: software
abstract: R package 'qgisprocess' provides seamless access
  to the 'QGIS' (https://qgis.org) processing
  toolbox using the standalone 'qgisprocess' command-line utility. Both native and
  third-party (plugin) processing providers are supported. Beside referring data sources
  from file, also common objects from 'sf', 'terra' and 'stars' are supported. The
  native processing algorithms are documented by QGIS.org (2024)
  https://docs.qgis.org/latest/en/docs/usermanual/processing_algs/.
identifiers:
- type: url
  value: https://r-spatial.github.io/qgisprocess/
version: 0.4.1

GitHub Events

Issues and Pull Requests

Last synced: 7 months ago

Packages