Plugins

Plugins provide a way of adding new functionality to RiskScape, or extending existing functionality.

RiskScape usually comes with several plugins installed by default. In fact, almost all of the tools that are required for loss modelling have been added into RiskScape by plugins. The RiskScape engine itself simply provides a skeleton framework for building data processing models that plugins can add to.

This simplified diagram of the software architecture highlights the role that plugins play (click to enlarge it).

A simplified software architecture that shows functionality, such as Python support, is provided via RiskScape plugins.

You can see what plugins have been loaded into your version of RiskScape by running:

riskscape --version

Default Plugins

If you have installed RiskScape in the standard location then default plugins are located at:

  • C:\RiskScape\riskscape\plugins (Windows)

  • /opt/riskscape/riskscape/plugins (Linux or Mac)

Optional Plugins

RiskScape comes with some plugins that are optional. Plugins might be optional because they require some other software to be installed on your computer in order to run. These plugins could cause errors on startup if the required software is not installed.

Some plugins are optional because they are intended for a very niche use-case, and so they are not generally applicable to loss modelling.

If you have installed RiskScape in the standard location then optional plugins are located at:

  • C:\RiskScape\riskscape\plugins-optional (Windows)

  • /opt/riskscape/riskscape/plugins-optional (Linux or Mac)

Refer to Settings file for how to load plugins.

Docker

Docker can be a simple way to package and distribute RiskScape to multiple users (within RiskScape’s licensing terms), particularly when you want to enable additional plugins by default.

For example, the HDF5 and OGR RiskScape plugins rely on other third-party software components being installed. Packaging up RiskScape into a docker image means that the dependent components will always be installed correctly and available.

A RiskScape docker image can be manually built from the RiskScape source code by using the bin/docker-build.sh script.

Beta plugin

The Beta plugin adds features to RiskScape that may be:

  • subject to change

  • experimental

  • not yet production quality

This plugin is used to make these features available to select users, for testing, whilst preventing them from being used inadvertently by other users.

Note

When the Beta plugin is enabled you will get a warning on RiskScape started up that the plugin has been loaded, and experimental features are available.

Tip

You can use a separate settings.ini to temporarily enable beta features for testing. For example, you could create a settings.ini file in your current working directory with the beta plugin enabled, and then load these settings using riskscape -H . at the start of your command.

Beta plugin features

GeoPackage input and output

Adds support for reading and writing GeoPackage files.

Refer to:

riskscape format info geopackage

PostGIS output

This allows RiskScape output to be saved to a PostGIS database instead of files saved to the file system.

To use specify an output location like: --output postgis://USER@HOST/DATABASE and if necessary set a PGPASSWORD environment variable with the database user’s password.

RiskScape will create and populate tables in the database with the model run results.

NetCDF plugin

The NetCDF plugin adds support for opening NetCDF files (i.e. files with a .nc file extension). The NetCDF plugin can be used without installing any other software. Refer to How to use NetCDF files in a model for more details.

HDF5 plugin

The HDF5 plugin adds support for opening HDF5 files (i.e. files with a .hdf5 file extension).

The HDF5 plugin is dependent on having the HDF5 library installed on your system, i.e. the libhdf5_java.so library. Currently RiskScape is supported against HDF5 version 1.12.2.

If this library is installed, but RiskScape cannot find it on your system PATH variable, then you could try adding the following to your settings INI file.

[hdf5]
lib_path = <path_to_library>

USGS plugin

The USGS plugin adds support for loading data from USGS ShakeMaps into RiskScape models. The USGS plugin also requires that you have the HDF5 library installed and configured on your system (see previous section).

OGR plugin

The OGR plugin adds support for extra vector file formats (e.g geodatabase .gdb).

The plugin requires separate third-party OGR software to be installed. OGR software is part of GDAL.

Installing OGR

There are two parts to installing OGR for RiskScape. They are:

  1. Installing the OGR software

  2. Making the OGR software available to the RiskScape plugin

Note

When you next update RiskScape, you will have to make OGR available to RiskScape again, i.e. you will have to follow the second half of these steps again. This is because you are copying an OGR file into the RiskScape installation directory, and that directory will be deleted as part of upgrading.

On an Ubuntu Linux system OGR can be installed with:

sudo apt-get install -y gdal-bin libgdal-java
# Now make OGR available to RiskScape
ln -s /usr/share/java/gdal.jar /opt/riskscape-cli/plugins-optional/ogr/

On Windows OGR installation is more complicated.

An OGR installer can be downloaded from GIS Internals

  • choose the most recent GDAL version

  • choose the compiler/arch that best matches your computer (most likely x64, and the most recent compiler. I have used GDAL 3.2.1, MSVC 2019 successfully)

  • on the next page download gdal-xxx-xxxx-core.msi Generic installer for the GDAL core components

Double-click the downloaded gdal-xxx-xxxx-core.msi file to install it. Select the ‘Typical’ installation. This will install GDAL to C:\Program Files\GDAL

To make OGR available to RiskScape:

  • copy C:\Program Files\GDAL\java\gdal.jar to C:\RiskScape\riskscape\plugins-optional\ogr

On Windows, some environment variables also need to be edited or set in order to use the downloaded GDAL software. A simple approach is to make this part of the Desktop shortcut that you use to run RiskScape:

cd C:\RiskScape_Projects\

@echo off

set PATH=C:\Program Files\GDAL;%PATH%
set GDAL_DATA=C:\Program Files\GDAL\gdal-data
set PROJ_LIB=C:\Program Files\GDAL\projlib

doskey riskscape=C:\RiskScape\riskscape\bin\riskscape.bat --load-plugin=C:\RiskScape\riskscape\plugins-optional\ogr $*

cmd -c