Automatic search and find of the installed GIS software binaries is performed by the find functions. Depending of you OS and the number of installed versions you will get a dataframe providing the binary and module folders.
# find all SAGA GIS installations at the default search location
require(link2GI)
saga <- link2GI::findSAGA()
saga
Same with GRASS and OTB
# find all SAGA GIS installations at the default search location
require(link2GI)
grass <- link2GI::findGRASS()
grass
otb <- link2GI::findOTB()
otb
The find functions are providing an overview of the installed software. This functions are not establishing any linkages or changing settings.
If you just call link2GI on the fly , that means for a single temporary operation, there will be no need for setting up folders and project structures. If you work on a more complex project it is seems to be helpful to support this by a fixed structure. Same with existing GRASS projects wich need to be in specific mapsets and locations.
A straightforward (you may call it also dirty) approach is the ìnitProjfunction that creates folder structures (if not existing) and establishes (if wanted) global variables containing the pathes as strings.
# find all SAGA GIS installations at the default search location
require(link2GI)
link2GI::initProj(projRootDir = tempdir(),
projFolders = c("data/",
"data/level0/",
"data/level1/",
"output/",
"run/",
"fun/"),
path_prefix = "path_to_" ,
global =TRUE)
In earlier times it has been pretty cumbersome to link the correct SAGA GIS version. Since the version 1.x.x of RSAGA things turned much better. The new RSAGA::rsaga.env() function is at getting the first RSAGA version in the search path. For using RSAGA with link2GI it is strongly recommended to call RSAGA.env() with the preferred path as provided by a ' findSAGA() call. It is also possible to provide the version number as shown below. Storing the result in adequate variables will then even give the opportunity to easyly switch between different SAGA GIS installations.
saga1<-link2GI::linkSAGA(ver_select = 1)
saga1
sagaEnv1<- RSAGA::rsaga.env(path = saga1$sagaPath)
linkGRASS Initializes the session environment and the system paths for an easy access to GRASS GIS 7.x./8.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. These properties are used to initialize either a temporary or a permanent rgrass environment including the correct GRASS 7/8 database structure. If you provide none of the before mentioned objects linkGRASS will create a EPSG:4326 world wide location.
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 manually findGRASS. Then call linkGRASS with the returned version arguments of your choice.
The function linkGRASS 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 environment.
If you have more than one valid installation and run linkGRASS with the arguments select_ver = TRUE, then you will be ask to select one.
The most common way to use GRASS is just for one call or algorithm. So the user is not interested in the cumbersome setting up of all parameters. linGRASS7(georeferenced-dataset) does an automatic search and find all GRASS binaries using the georeferenced-dataset object for spatial referencing and the necessary other settings.
NOTE: This is the highly recommended linking procedure for all on the fly calls of GRASS. Please note also: If more than one GRASS installation is found the one with the highest version number is selected automatically.
Have a look at the following examples which show a typical call for the well known spand sf vector data objects.
Starting with sp.
# get meuse data as sp object and link it temporary to GRASS
require(link2GI)
require(sp)
# get data
data(meuse)
# add georeference
coordinates(meuse) <- ~x+y
proj4string(meuse) <-CRS("+init=epsg:28992")
# Automatic search and find of GRASS binaries
# using the meuse sp 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 the highest version will be choosed
linkGRASS(meuse)
Now do the same with sf based data.
require(link2GI)
require(sf)
# 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 the highest version will be choosed
grass<-linkGRASS(nc,returnPaths = TRUE)
The second most common situation is the usage of an existing GRASS location and project either with existing data sets or manually provided parameters.
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"))
# CREATE and link to a permanent GRASS folder at "projRootDir", location named "project1"
linkGRASS(nc, gisdbase = projRootDir, location = "project1")
# ONLY LINK to a permanent GRASS folder at "projRootDir", location named "project1"
linkGRASS(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"))
linkGRASS(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"))
linkGRASS(gisdbase = projRootDir,
location = "nc_spatial_params",
spatial_params = c(-84.32385, 33.88199,-75.45698,36.58965,proj4_string))
The full disk search can be cumbersome especially running Windos it can easily take 10 minutes and more. So it is helpful to provide a searchpath for narrowing down the search. Searching for GRASS installations in the home directory you may use the following command.
# Link the GRASS installation and define the search location
linkGRASS(nc, search_path = "~")
If you already did a full search and kow your installation fo example using the command findGRASS you can use the result directly for linking.
findGRASS()
instDir version installation_type
1 /opt/grass 7.8.1 grass78
# now linking it
linkGRASS(nc,c("/opt/grass","7.8.15","grass78"))
# corresponding linkage running windows
linkGRASS(nc,c("C:/Program Files/GRASS GIS7.0.5","GRASS GIS 7.0.5","NSIS"))
Finally some more specific examples related to interactive selection or OS specific settings.
Choose manually the GRASS installation additionally using the meuse sf object for spatial referencing
linkGRASS(nc, ver_select = TRUE)
Creating and linking a permanent GRASS gisdbase (folder structure) at “~/temp3” with the standard mapset “PERMANENT”“ and the location named "project1”. For all spatial attributes use the the meuse sf object.
linkGRASS(x = nc,
gisdbase = "~/temp3",
location = "project1")
Link to the permanent GRASS gisdbase (folder structure) at “~/temp3” with the standard mapset “PERMANENT” and the location named “project1”. For all spatial attributes use the formerly referencend nc sf object parameter.
linkGRASS(gisdbase = "~/temp3", location = "project1",
gisdbase_exist = TRUE)
Setting up GRASS manually with spatial parameters of the meuse data
linkGRASS(spatial_params = c(178605,329714,181390,333611,
"+proj=sterea +lat_0=52.15616055555555
+lon_0=5.38763888888889 +k=0.9999079
+x_0=155000 +y_0=463000 +no_defs
+a=6377397.155 +rf=299.1528128
+towgs84=565.4171,50.3319,465.5524,
-0.398957,0.343988,-1.8774,4.0725
+to_meter=1"))
link2GI supports the use of the Orfeo Toolbox with a listbased simple wrapper function. Actually two functions parse the modules and functions syntax dumps and generate a command list that is easy to modify with the necessary arguments.
Usually you have to get the module list first:
# link to the installed OTB
otblink<-link2GI::linkOTB()
# get the list of modules from the linked version
algo<-parseOTBAlgorithms(gili = otblink)
Based on the modules of the current version of OTB you can then choose the module(s) you want to use.
## for the example we use the edge detection,
algoKeyword<- "EdgeExtraction"
## extract the command list for the choosen algorithm
cmd<-parseOTBFunction(algo = algoKeyword, gili = otblink)
## print the current command
print(cmd)
Admittedly this is a very straightforward and preliminary approach. Nevertheless it provids you a valid list of all OTB API calls that can easily manipulated for your needs. The following working example will give you an idea how to use it.
require(link2GI)
require(raster)
require(listviewer)
otblink<-link2GI::linkOTB()
projRootDir<-tempdir()
data('rgb', package = 'link2GI')
raster::plotRGB(rgb)
r<-raster::writeRaster(rgb,
filename=file.path(projRootDir,"test.tif"),
format="GTiff", overwrite=TRUE)
## for the example we use the edge detection,
algoKeyword<- "EdgeExtraction"
## extract the command list for the choosen algorithm
cmd<-parseOTBFunction(algo = algoKeyword, gili = otblink)
## get help using the convenient listviewer
listviewer::jsonedit(cmd$help)
## define the mandantory arguments all other will be default
cmd$input <- file.path(projRootDir,"test.tif")
cmd$filter <- "touzi"
cmd$channel <- 2
cmd$out <- file.path(projRootDir,paste0("out",cmd$filter,".tif"))
## run algorithm
retStack<-runOTB(cmd,gili = otblink)
## plot filter raster on the green channel
plot(retStack)