{"id":13857779,"url":"https://github.com/r-spatial/RQGIS3","last_synced_at":"2025-07-13T22:31:11.027Z","repository":{"id":66205476,"uuid":"153804015","full_name":"r-spatial/RQGIS3","owner":"r-spatial","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-13T21:42:33.000Z","size":10022,"stargazers_count":72,"open_issues_count":12,"forks_count":19,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-07-07T22:39:27.202Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-spatial.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-19T15:26:09.000Z","updated_at":"2025-04-22T14:50:59.000Z","dependencies_parsed_at":"2024-11-22T15:34:00.170Z","dependency_job_id":null,"html_url":"https://github.com/r-spatial/RQGIS3","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/r-spatial/RQGIS3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-spatial%2FRQGIS3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-spatial%2FRQGIS3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-spatial%2FRQGIS3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-spatial%2FRQGIS3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-spatial","download_url":"https://codeload.github.com/r-spatial/RQGIS3/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-spatial%2FRQGIS3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265218201,"owners_count":23729496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-05T03:01:46.791Z","updated_at":"2025-07-13T22:31:11.012Z","avatar_url":"https://github.com/r-spatial.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n# RQGIS3\n\n[![Travis build status](https://travis-ci.org/jannes-m/RQGIS3.svg?branch=master)](https://travis-ci.org/jannes-m/RQGIS3)\n[![CRAN status](https://www.r-pkg.org/badges/version/RQGIS3)](https://cran.r-project.org/package=RQGIS3)\n[![Coverage status](https://codecov.io/gh/jannes-m/RQGIS3/branch/master/graph/badge.svg)](https://codecov.io/github/jannes-m/RQGIS3?branch=master)\n[![StackOverflow](https://img.shields.io/badge/stackoverflow-rqgis-orange.svg)](https://stackoverflow.com/questions/tagged/rqgis)\n\n## Use qgis_process instead of RQGIS3\n\nFrom now on, we discourage the usage of **RQGIS3** since it is no longer actively maintained and due to various unresolvable issues (see also next section).\nHowever, the good new is that there is a new [standalone executable](https://github.com/qgis/QGIS/pull/34617) available from QGIS 3.14 onwards.\nThis means, one can now run QGIS processing algorithms from the command line with ease.\nThe tool is easy to use, takes care of setting the environmental variables to run QGIS and the user no longer has to use Python.\nIn short, this seems to be the perfect replacement for **RQGIS3**.\nEven better, @paleolimbot is already developing an R package calling `qgis_process` with the help of **processx**. \nPlease refer to [qgisprocess](https://github.com/paleolimbot/qgisprocess) for more information and how to use the package.\n\nSince **qgisprocess** is still under active development, we show here how to use the standalone executable `qgis_process` using simple `system2` calls.\nWindows users must specify the path to the OSGeo4W Shell in order to run `qgis_process`, which for now is called `qgis_process-qgis` under Windows.\n\n```{r, eval=FALSE}\n# specify path to OSGeo4W Shell on your system.\n# Path depends on where you have installed QGIS 3.14 on your system, hence, you\n# might have to adjust the path\nos_shell = \"C:/OSGEO4~1/OSGeo4W.bat\"\n# another typical location is:\n# os_shell = \"C:/Program Files/QGIS 3.14/OSGeo4W.bat\"\nsystem2(os_shell, args = \"qgis_process-qgis\")\n```\n\nWindows users please adjust all following commands using the syntax given in the chunk above.\nBy contrast, UNIX users can simply type:\n\n```{r}\nsystem(\"qgis_process\", intern = TRUE)\n```\n\nRunning `qgis_process` without specifying any parameters lists the available commands.\nLet's have a look at the available geoprocessing algorithms.\n\n```{r}\nalgs = system(\"qgis_process list\", intern = TRUE)\nhead(algs, 20)\n```\n\nTo test if we can actually process some geodata, let's try to find the centroid of a spatial polygon layer.\nFirst, we need to know which centroid algorithms are at our disposal.\n\n```{r}\ngrep(\"centroid\", algs, value = TRUE)\n```\n\nLet's use `native:centroids` to find the centroids of the NC dataset.\nFirst, we need to find out which parameters are required by `native:centroids`.\n\n```{r}\nsystem(\"qgis_process help native:centroids\", intern = TRUE)\n```\n\nWe have to specify INPUT and OUTPUT.\n\n```{r}\nnc_path = system.file(\"shape/nc.shp\", package = \"sf\")\nout_path = tempfile(fileext = \".gpkg\")\ncmd = sprintf(\"qgis_process run native:centroids --INPUT=%s --OUTPUT=%s\",\n              nc_path, out_path)\nsystem(cmd, intern = TRUE)\n```\n\nIt seemed to have worked.\nTo check the output, let us read it in and plot it.\n\n```{r, message=FALSE, warning=FALSE}\nlibrary(\"sf\")\nlibrary(\"dplyr\")\n\n# read in the data\nnc = read_sf(nc_path)\nnc_cen = read_sf(out_path)\n\n# first plot nc polygons\nst_geometry(nc) %\u003e% plot\n# then add the centroids computed by QGIS\nst_geometry(nc_cen) %\u003e% plot(pch = 16, col = \"red\", add = TRUE)\n```\n\nExcellent. \nWe have computed the centroids of the nc polygons using QGIS via the command line.\n\n\n## ATTENTION\n\n**RQGIS3 crashes RStudio R session on UNIX-based OS**\n\nThough **RQGIS3** works when running it in a plain R session in the terminal, it crashes the R session when ran inside RStudio on UNIX-based OS (see https://github.com/r-spatial/RQGIS3/issues/10 and https://github.com/rstudio/rstudio/issues/4606).\nIf Linux and MacOS users would like to use **RQGIS3** in conjunction with RStudio, we recommend to use the [geocompr docker image](https://hub.docker.com/r/robinlovelace/geocompr/).\nPlease refer also to the instructions on the [geocompr landing page](https://github.com/robinlovelace/geocompr#running-geocompr-code-in-docker) how to use the docker image.\nSince **RQGIS3** and RStudio work in harmony under Windows, a further alternative would be to use a virtual box running Windows.\n\n## Description\n\n**RQGIS3** establishes an interface between R and QGIS3, i.e., it allows the user to access QGIS3 functionalities from within R. \nIt achieves this by establishing a tunnel to the Python QGIS3 API via the [reticulate-package](https://github.com/rstudio/reticulate).\nThis provides the user with an extensive suite of GIS functions, since QGIS3 allows you to call native as well as third-party algorithms via its processing framework (see\nalso [https://docs.qgis.org/testing/en/docs/user_manual/processing/index.html](https://docs.qgis.org/testing/en/docs/user_manual/processing/index.html)).\nThird-party providers include among others GDAL, GRASS GIS, and SAGA GIS.\n**RQGIS3** brings you this incredibly powerful geoprocessing environment to the R console.\n\nPlease check also out our paper presenting **RQGIS (2)** in detail:\n\n\u003cdiv style = \"text-align:center\"\u003e \n\u003ca href = \"https://rjournal.github.io/archive/2017/RJ-2017-067/RJ-2017-067.pdf\"\u003ehttps://rjournal.github.io/archive/2017/RJ-2017-067/RJ-2017-067.pdf\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align = \"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jannes-m/RQGIS/master/figures/r_qgis_puzzle.png\" width=\"40%\"/\u003e\n\u003c/p\u003e\n\nThe main advantages of **RQGIS3** are:\n\n1. It provides access to QGIS3 functionalities.\nThereby, it calls the Python QGIS3 API but R users can stay in their programming environment of choice without having to touch Python3.\n2. It offers a broad suite of geoalgorithms making it possible to solve most GIS problems. \n3. R users can use just one package (**RQGIS3**) instead of using **RSAGA** and **rgrass7** to access SAGA and GRASS functions. \nThis, however, does not mean that **RSAGA** and **rgrass7** are obsolete since both packages offer various other advantages. \nFor instance, **RSAGA** provides many user-friendly and ready-to-use GIS functions such as `rsaga.slope.asp.curv()` and `multi.focal.function()`.\n\n## Package installation\n\nIn order to run **RQGIS3** properly, you need to download various third-party software packages. \nOur vignette should help you with the download and installation procedures on various platforms (Windows, Linux, Mac OSX). To access it, use `vignette(\"install_guide\", package = \"RQGIS3\")`. \n\nYou can install:\n\n\u003c!--\n- the latest released version from CRAN with:\n\n```{r, eval = FALSE}\ninstall.packages(\"RQGIS3\")\n```\n--\u003e\n\n- the latest **RQGIS3** development version from Github with:\n\n```{r, eval=FALSE}\nremotes::install_github(\"jannes-m/RQGIS3\")\n```\n\n## Usage\n\nSubsequently, we will show you a typical workflow of how to use **RQGIS3**. \nBasically, we will follow the steps also described in the [QGIS documentation](https://docs.qgis.org/testing/en/docs/user_manual/processing/console.html). \nIn our first and very simple example we simply would like to retrieve the centroid coordinates of a spatial polygon object. \nFirst, we will download the administrative areas of Germany using the **raster** package.\n\n```{r ger_download, eval=FALSE, warning=FALSE, error=FALSE, message=FALSE}\n# attach packages\nlibrary(\"raster\")\nlibrary(\"rgdal\")\n\n# download German administrative areas \nger = getData(name = \"GADM\", country = \"DEU\", level = 1)\n# ger is of class \"SpatialPolygonsDataFrame\"\n```\n\nNow that we have a spatial object, we can move on to using **RQGIS3**. \nFirst of all, we need to specify all the paths necessary to run the QGIS-API. \nFortunately, `set_env()` does this for us (assuming that QGIS and all necessary dependencies were installed correctly). \nThe only thing we need to do is: specify the root path to the QGIS-installation. \nIf you do not specify a path, `set_env()` tries to find the OSGeo4W-installation first in the 'C:/OSGeo4W'-folders. \nIf this is unsuccessful, it will search your C: drive though this might take a while. \nIf you are running **RQGIS3** under Linux or on a Mac, `set_env()` assumes that your root path is `/usr` and `/applications/QGIS.app/Contents`, respectively.\nPlease note, that most of the **RQGIS3** functions, you are likely to work with (such as `find_algorithms()`, `get_args_man()` and `run_qgis()`), require the output list (as returned by `set_env()`) containing the paths to the various installations necessary to run QGIS3 from within R. \nThis is why, `set_env()` caches its result in a temporary folder, and loads it back into R when called again (to overwrite an existing cache, set parameter `new` to `TRUE`).\n\n```{r, warning=FALSE, error=FALSE, eval=FALSE}\n# attach RQGIS3\nlibrary(\"RQGIS3\")\n\n# set the environment, i.e. specify all the paths necessary to run QGIS from \n# within R\nset_env()\n# under Windows set_env would be much faster if you specify the root path:\n# set_env(\"C:/OSGeo4W~1\")\n\n\n## $root\n## [1] \"C:\\\\OSGeo4W64\"\n##\n## $qgis_prefix_path\n## [1] \"C:\\\\OSGeo4W64\\\\apps\\\\qgis\"\n##\n## $python_plugins\n## [1] \"C:\\\\OSGeo4W64\\\\apps\\\\qgis\\\\python\\\\plugins\"\n```\n\nNext, `open_app()` establishes a tunnel to the Python QGIS3 API which naturally is the basis of any QGIS3 geoprocessing from within R.\n\n```{r, eval=FALSE}\nopen_app()\n```\n\nInternally, `open_app()` first sets all necessary paths with the help of `set_env()` (among others the path to the QGIS Python binary) to run QGIS3, and secondly opens a QGIS3 application with the help of [reticulate](https://github.com/rstudio/reticulate). \n`open_app()` is run automatically by all **RQGIS3** functions that need access to the QGIS3 Python API.\n^[\nPlease note that the Python tunnel can only be closed by starting a new R session (see [https://github.com/rstudio/reticulate/issues/27](https://github.com/rstudio/reticulate/issues/27)). \nOn the one hand, this means that we only have to set up the Python environment once and consequently subsequent processing is faster. \nAdditionally, you can use your own Python commands to customize **RQGIS3** as you like. \nOn the other hand, it also means that once you have run `open_app()` for the first time, you have to stay with the chosen QGIS3 (LTR or developer version) and corresponding Python (Python 3) version for this session. \n]\n\nNext, we would like to find a QGIS3 geoalgorithm that is able to compute the centroids of a polygon vector layer. \nTo do so, we use `find_algorithms()`. \nHere, we look for a geoalgorithm that contains the word `centroid` in its short description.  \nNote that `search_term` also accepts regular expressions.\n\n```{r, warning=FALSE, error=FALSE, eval=FALSE}\nfind_algorithms(search_term = \"centroid\", name_only = TRUE)\n\n#\u003e[1] \"native:centroids\"\n#\u003e[2] \"qgis:generatepointspixelcentroidsalongline\"     \n#\u003e[3] \"qgis:generatepointspixelcentroidsinsidepolygons\"\n#\u003e[4] \"saga:polygoncentroids\"  \n```\n\nThis returns four functions we could use.\nHere, we'll choose the QGIS3 function named `native:centroids`. \nSubsequently, we would like to know how we can use it, i.e., which function parameters we need to specify.\n\n```{r, error=FALSE, eval=FALSE}\nget_usage(alg = \"native:centroids\")\n\n#\u003e Centroids (native:centroids)\n#\u003e \n#\u003e This algorithm creates a new point layer\n#\u003e with points representing the centroid of the geometries in an input layer.\n#\u003e \n#\u003e The attributes associated to each point in the output layer are the same ones associated to the original features.\n#\u003e \n#\u003e \n#\u003e ----------------\n#\u003e Input parameters\n#\u003e ----------------\n#\u003e \n#\u003e INPUT: Input layer\n#\u003e \n#\u003e \tParameter type:\tQgsProcessingParameterFeatureSource\n#\u003e \n#\u003e \tAccepted data types:\n#\u003e \t\t- str: layer ID\n#\u003e \t\t- str: layer name\n#\u003e \t\t- str: layer source\n#\u003e \t\t- QgsProcessingFeatureSourceDefinition\n#\u003e \t\t- QgsProperty\n#\u003e \t\t- QgsVectorLayer\n#\u003e \n#\u003e ALL_PARTS: Create point on surface for each part\n#\u003e \n#\u003e \tParameter type:\tQgsProcessingParameterBoolean\n#\u003e \n#\u003e \tAccepted data types:\n#\u003e \t\t- bool\n#\u003e \t\t- int\n#\u003e \t\t- str\n#\u003e \t\t- QgsProperty\n#\u003e \n#\u003e OUTPUT: Centroids\n#\u003e \n#\u003e \tParameter type:\tQgsProcessingParameterFeatureSink\n#\u003e\n#\u003e \tAccepted data types:\n#\u003e \t\t- str: destination vector file\n#\u003e e.g. d:/test.shp\n#\u003e \t\t- str: memory: to store result in temporary memory layer\n#\u003e \t\t- str: using vector provider ID prefix and destination URI\n#\u003e e.g. postgres:... to store result in PostGIS table\n#\u003e \t\t- QgsProcessingOutputLayerDefinition\n#\u003e \t\t- QgsProperty\n#\u003e \n#\u003e ----------------\n#\u003e Outputs\n#\u003e ----------------\n#\u003e \n#\u003e OUTPUT:  \u003cQgsProcessingOutputVectorLayer\u003e\n#\u003e \tCentroids\n```\n\nConsequently `native:centroids` only expects a parameter called `INPUT`, i.e., the path to a spatial polygon file whose centroid coordinates we wish to extract, and a parameter called `OUTPUT`, i.e., the path to the output spatial object. \nSince it would be tedious to specify manually each and every function argument, especially if a function expects more than two or three arguments, we have written a convenience function, named `get_args_man()`, that retrieves all function parameters, and the respective default values as arguments for a given QGIS geoalgorithm. \nIt returns these values in the form of a list. \nIf a function argument lets you choose between several options (drop-down menu in a GUI), setting `get_arg_man()`'s `options`-argument to `TRUE` makes sure that the first option will be selected (QGIS GUI behavior).\nFor example, `qgis:addfieldtoattributestable` has three options for the `FIELD_TYPE`-parameter, namely integer, float and string. \nSetting `options` to `TRUE` means that the field type of your new column will be of type integer.\n\n```{r, error=FALSE, eval=FALSE}\nparams = get_args_man(alg = \"native:centroids\")\nparams\n#\u003e$INPUT\n#\u003e[1] \"None\"\n#\u003e\n#\u003e$ALL_PARTS\n#\u003e[1] \"False\"\n#\u003e\n#\u003e$OUTPUT\n#\u003e[1] \"None\"\n```\n\nIn our case, `native:centroids` has only two function arguments and no default values. Naturally, we need to specify manually our input and output layer. \nWe can do so in two ways. \nEither we use directly our parameter-argument list... \n\n```{r, eval=FALSE}\nparams$INPUT = ger\nparams$OUTPUT = file.path(tempdir(), \"ger_coords.shp\")\nout = run_qgis(alg = \"native:centroids\",\n               params = params,\n               load_output = TRUE)\n#\u003e$OUTPUT\n#\u003e[1] \"/tmp/RtmpC6SKby/ger_coords.shp\"\n```\n\n... or we can use R named arguments in `run_qgis()`\n\n```{r, eval=FALSE}\nout = run_qgis(alg = \"native:centroids\",\n               INPUT = ger,\n               OUTPUT = file.path(tempdir(), \"ger_coords.shp\"),\n               load_output = TRUE)\n#\u003e$OUTPUT\n#\u003e[1] \"/tmp/RtmpC6SKby/ger_coords.shp\"\n```\n\nPlease note that our `INPUT` is a spatial object residing in R's global environment. \nOf course, you can also use a path to specify `INPUT` (e.g. \"ger.shp\") which is the better option if your data is already somewhere stored on your hard drive.\nFinally, `run_qgis()` calls the QGIS API to run the specified geoalgorithm with the corresponding function arguments. \nSince we set `load_output` to `TRUE`, `run_qgis()` automatically loads the QGIS output back into R (`sf`-objects in the case of vector data and `raster`-objects in the case of raster data). \nNaturally, we would like to check if the result meets our expectations. \n\n```{r, fig.width=5, fig.height=5, align=\"center\", eval=FALSE}\n# first, plot the federal states of Germany\nplot(ger)\n# next plot the centroids created by QGIS\nplot(out$geometry, pch = 21, add = TRUE, bg = \"lightblue\", col = \"black\")\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jannes-m/RQGIS/master/https://raw.githubusercontent.com/jannes-m/RQGIS/master/figures/10_plot_ger.png\" width=\"60%\"/\u003e\n\u003c/p\u003e\n\nOf course, this is a very simple example. \nWe could have achieved the same using `sf::st_as_sf(ger) %\u003e% sf::st_centroid()`. \nFor a more detailed introduction to **RQGIS3** and more complex examples have a look at our paper:\n\n\u003cdiv style = \"text-align:center\"\u003e \n\u003ca href = \"https://rjournal.github.io/archive/2017/RJ-2017-067/RJ-2017-067.pdf\"\u003ehttps://rjournal.github.io/archive/2017/RJ-2017-067/RJ-2017-067.pdf\u003c/a\u003e\n\u003c/div\u003e\n\n## macOS\n\nThe following setup works to execute `find_algorithms()` on macOS 10.14.6 (Mojave).\n\nInstalled from `homebrew/osgeo4mac`:\n\n- osgeo-qgis (v3.8.0)\n- osgeo-gdal (v2.4.1)\n- osgeo-gdal-python (v2.4.1)\n- spatialindex (v1.9.0)\n- osgeo-proj@5 (soft linked `ln -s /usr/local/opt/osgeo-proj/lib/libproj.15.dylib /usr/local/opt/osgeo-proj/lib/libproj.13.dylib`)\n\nWhen running `open_app()` you'll see a bunch of warnings but you should be able to run `find_algorithms()`.\n\nThe current `osgeo-qgis` formula does not work with gdal v3.0 even though the latter is the latest version of `osgeo-gdal`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-spatial%2FRQGIS3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-spatial%2FRQGIS3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-spatial%2FRQGIS3/lists"}