-
Notifications
You must be signed in to change notification settings - Fork 20
/
README.Rmd
160 lines (106 loc) · 7.01 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
---
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%",
dpi = 300
)
```
# qgisprocess
<img src="man/figures/qgisprocess.svg" align="right" hspace="10" vspace="0" width="20%">
<!-- badges: start -->
[](https://CRAN.R-project.org/package=qgisprocess)
[](https://doi.org/10.5281/zenodo.8260794)
[](https://github.com/r-spatial/qgisprocess/actions/workflows/R-CMD-check.yaml)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://app.codecov.io/gh/r-spatial/qgisprocess/tree/main)
<!-- badges: end -->
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 <https://download.qgis.org/>.
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 <https://r-spatial.github.io/qgisprocess/reference/index.html>.
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:
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:
- \<Reference to your work\>. Source code: \<URL\>.
_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