linkGRASS7: Locate and set up 'GRASS 7' API bindings

Description Usage Arguments Details Note Author(s) Examples

View source: R/linkGRASS.R

Description

Initializes the session environment and the system pathes for an easy acces to 'GRASS GIS 7.x'. The correct setup of the spatial and projection parameters is automatically performed by using either an existing and valid raster, sp or sf object, or manually by providing a list containing the minimum parameters needed.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
linkGRASS7(
  x = NULL,
  default_GRASS7 = NULL,
  search_path = NULL,
  ver_select = FALSE,
  gisdbase_exist = FALSE,
  gisdbase = NULL,
  use_home = FALSE,
  location = NULL,
  spatial_params = NULL,
  resolution = NULL,
  quiet = TRUE,
  returnPaths = TRUE
)

Arguments

x

raster or sp object

default_GRASS7

default is NULL If is NULL an automatic search for all installed versions is performed. If you provide a valid list the corresponding version is initialized. An example for OSGeo4W64 is: c("C:/OSGeo4W64","grass-7.0.5","osgeo4w")

search_path

path or mounting point that will be searched

ver_select

boolean if TRUE you may choose interactively the binary version (if found more than one), by default FALSE

gisdbase_exist

default is FALSE if set to TRUE the arguments gisdbase and location are expected to be an existing GRASS gisdbase

gisdbase

default is NULL, invoke tempdir() to the 'GRASS' database. Alternativeley you can provide a individual path.

use_home

default is FALSE, set the GISRC path to tempdir(), if TRUE the HOME or USERPROFILE setting is used for writing the GISRC file

location

default is NULL, invoke basename(tempfile()) for defining the 'GRASS' location. Alternativeley you can provide a individual path.

spatial_params

default is NULL. Instead of a spatial object you may provide the geometry as a list. E.g. c(xmin,ymin,xmax,ymax,proj4_string)

resolution

resolution in map units for the GRASS raster cells

quiet

boolean switch for supressing console messages default is TRUE

returnPaths

boolean if set to FALSE the pathes of the selected version are written to the PATH variable only, otherwise all paths and versions of the installed GRASS versions ae returned.

Details

The concept is straightforward but for an all days usage helpful. Either you need to provide a raster or sp sf spatial object which has correct spatial and projection properties or you may link directlxy to an existing 'GRASS' gisdbase and mapset. If you choose an spatial object to initialize a correct 'GRASS' mapset it is used to create either a temporary or a permanent rgrass7 environment including the correct 'GRASS 7' structure.

The most time consuming part on 'Windows' Systems is the search process. This can easily take 10 or more minutes. To speed up this process you can also provide a correct parameter set. Best way to do so is to call searchGRASSW or for 'Linux' searchGRASSX manually. and call linkGRASS7 with the version arguments of your choice. linkGRASS7 initializes the usage of GRASS7.

Note

'GRASS GIS 7' is excellently supported by the rgrass7 wrapper package. Nevertheless 'GRASS GIS' is well known for its high demands regarding the correct spatial and reference setup of workspace and environment requirements. This becomes even worse on 'Windows' platforms or if several alternative 'GRASS GIS' installations are available. If one knows what to do the rgrass7 package setup function rgrass7::initGRASS works fine under Linux. This is also valid for well known configurations under the 'Windows' operation system. Nevertheless on university lab or on company computers with restriced privileges and/or using different releases like the 'OSGeo4W' distribution and the 'GRASS 7' stand-alone installation, or different software releases (e.g. 'GRASS 7.0.5 and GRASS 7.2.0), it becomes often cumbersome or even impossible to get the correct linkages.
The function linkGRASS7 tries to find all valid 'GRASS GIS' binaries by analyzing the startup script files of 'GRASS GIS'. After identifying the 'GRASS GIS' binaries all necessary system variables and settings will be generated and passed to a temporary R enviroment.

If you have more than one valid installation and run linkGRASS7() without arguments, you will be ask to select one.

Author(s)

Chris Reudenbach

Examples

 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
## Not run: 
library(link2GI)
require(sf)

# proj folders
projRootDir<-tempdir()
paths<-link2GI::initProj(projRootDir = projRootDir,
                         projFolders = c("project1/"))
                         
# get  data                         
nc <- st_read(system.file("shape/nc.shp", package="sf"))

# Automatic search and find of GRASS binaries 
# using the nc sf data object for spatial referencing
# This is the highly recommended linking procedure for on the fly jobs
# NOTE: if more than one GRASS installation is found you have to choose. 
grass<-linkGRASS7(nc,returnPaths = TRUE)
if (grass$exist){

# CREATE and link to a permanent GRASS folder at "projRootDir", location named "project1" 
linkGRASS7(nc, gisdbase = projRootDir, location = "project1")   

# ONLY LINK to a permanent GRASS folder at "projRootDir", location named "project1" 
linkGRASS7(gisdbase = projRootDir, location = "project1", gisdbase_exist = TRUE )   


# setting up GRASS manually with spatial parameters of the nc data
proj4_string <- as.character(sp::CRS("+init=epsg:28992"))
linkGRASS7(spatial_params = c(178605,329714,181390,333611,proj4_string)) 

# creating a GRASS gisdbase manually with spatial parameters of the nc data 
# additionally using a peramanent directory "projRootDir" and the location "nc_spatial_params "
proj4_string <- as.character(sp::CRS("+init=epsg:4267"))
linkGRASS7(gisdbase = projRootDir,
           location = "nc_spatial_params",
           spatial_params = c(-84.32385, 33.88199,-75.45698,36.58965,proj4_string))
}

## Some more examples related to interactive selection or OS specific settings

# SELECT the GRASS installation and define the search location
linkGRASS7(nc, ver_select = TRUE, search_path = "~")

# SELECT the GRASS installation 
linkGRASS7(nc, ver_select = TRUE)

# Typical osge4W installation (QGIS), using the meuse sp data object for spatial referencing
linkGRASS7(nc,c("C:/Program Files/QGIS 2.18","grass-7.2.1","osgeo4W")) 

# Typical osgeo4W installation (rootdir), using the meuse sp data object for spatial referencing 
linkGRASS7(nc,c("C:/OSGeo4W64/","grass-7.2.2","osgeo4W"))


## End(Not run)

link2GI documentation built on Sept. 5, 2021, 5:34 p.m.