R user script

These plugin-based architecture is a way for the user to extend the features of GeoFIS. Each plugin is composed of a user defined R script, launched within the GeoFIS platform and therefore to benefit the whole environment. An entry is added in the “Process” menu for each enabled plugin.

Plugins folder

  • On Windows the plugins folder is located in “C:\ProgramData\GeoFIS\plugins”. The “C:\ProgramData” folder may be hidden in the file explorer, follow these show hidden files help to display the plugins folder.
  • On Linux the plugins folder is located in “/var/lib/geofis/plugins”.

The subfolder “R” includes as many folders as user plugins. Each plugin folder contains the properties file “plugin.properties” and at least 1 R script file.

Plugin Properties

Metadata

In order to make the plugin loadable for GeoFIS you have to provide some metadata in the “plugin.properties” file.

  • plugin.id the identifier of the plugin (must be unique for all installed plugins) with some name restrictions.
  • plugin.process the process name (GeoFIS process menu entry name. The default value is the plugin.id).
  • plugin.version the version of the plugin with the syntax X.Y.Z.
  • plugin.input the spatial input data type (allowed types: “point”, “polygon”, “vector” or “raster”. The default value is “point”. “vector” means “point” or “polygon”).
  • plugin.output the spatial output data type (allowed types: “point”, “polygon”, “input” or “raster”. The default value is “input”. “input” means the same type as input data).
  • Optional metadata:
    • plugin.description a description for the plugin.
    • plugin.provider the name of the plugin provider / author.
    • plugin.packages the list of R packages (comma separated) needed for the plugin.
    • plugin.license the license of the plugin.

Parameters

The main plugin R script can accepts some user parameters. Each parameter is described in the “plugin.properties” file by properties plugin.parameter1 to plugin.parameter'n'.

The parameter property syntax is: plugin.parameter'n' = 'name' 'type' [range] [layer name]

  • n is the number of the parameter (start at 1).
  • name is the parameter name with some name restrictions.
  • Allowed type are “text”, “integer”, “real”, “layer” or “attribute”. The default type is “text”.
    • The “layer” type allows the user to load an additional layer in the plugin, for example a border or additional data. Supported layers are Shapefile or raster GeoTIFF.
    • The “attribute” type allows the user to select an attribute (or band for raster) in a layer. The user can specify a “layer_name” (the name of a “layer” parameter) or “input” for the input layer. The default is “input”.
  • The range is optional and only used for “integer” or “real” type. The range is used to control the input parameter validity. No control if the range is not specified.
  • The layer name is optional and only used for “attribute” type. This layer name refers to an existing “layer” parameter. The default value is “input”.

The range syntax is: lower upper endpoints comma separated enclosed with brackets / parentheses for inclusive / exclusive values.

  • For example [0, 10] for a range with included enpoints, (0, 10) for a range with excluded enpoints.
  • Exclusions can be mixed (0, 10] or [0, 10).
  • Real values are allowed with dot decimal separator [0.5, 1.5].
  • Infinite range if endpoint is missed: [0,) for at least 0. (,10] for at most 10. (0,) for greater than 0. (,10) for lesser than 10.

Results

The main plugin R script can returns some results. These results will be displayed in the GeoFIS plugin window. Each result is described in the “plugin.properties” file by properties plugin.result1 to plugin.result'n'.

The result property syntax is: plugin.result'n' = 'name'

  • n is the number of the result (start at 1).
  • name is the result name with some name restrictions.

Name restrictions

Because plugin.id, plugin.parameter, plugin.result name is used as R variable, a valid R variable name consists of letters, numbers, the dot and underline characters. The name must start with a letter or a dot not followed by a number.
Reserved words “input”, “text”, “integer”, “real”, “attribute” and “layer” are not allowed for parameter name.

Plugin script

The main R script called “plugin-class.R” contains the main R class of the plugin (based on R6 class). The custom R code can be splitted in multiple R files. All R files in the plugin folder will be launched by GeoFIS.

  • The name of this class must be prefixed with the plugin.id.
  • Your code must be inserted between the “start / end custom code” comments of the perform() method.
  • The field “private$.input” contains spatial input data selected from GeoFIS process menu, converted to object of the sp package:
  • The field “private$.output” must contains the result spatial data of the plugin, displayed in GeoFIS as the output layer. Supported objects are:
  • The name of required R packages for the plugin must be supplied in the plugin.packages metadata.
  • The parameters are accessible within the script by their name using the syntax “self$name”. As the R6 class is not locked “lock_objects = FALSE”, the plugin parameters are added dynamically to the class, without the need to explicitly add the parameter as field of the class.
  • The “layer” parameters are converted to the same R object as the input data.
  • The “attribute” parameter is converted to R character.

Example Plugins

2 example plugins are provided:

  • template: the template to use to make a new plugin (do nothing by default)
  • sample: this plugin, designed to show the various possibilities that are offered to plugins, takes a subset of the input data and returns it as an output layer. The size of the subset is an input parameter called “sample_percent”, a percentage of the whole size.

New Plugin

To make a new plugin:

  • copy / paste the template folder to a folder with the name of your plugin.
  • edit the metadata of your plugin in the file “plugin.properties”.
  • edit the main class “plugin-class.R”:
    • rename the class with the prefix plugin.id.
    • insert your code inside the perform() method.
  • restart GeoFIS

See the plugin example sample.

Enable / Disable plugins

You can enable or disable any plugin by editing the file “disabled.txt” in the root of the plugins folder. All plugin.id added in these file will be ignored. The others are available at the next start of GeoFIS.