FICUS consists of two components, the FICUS/Server and the FICUS/UI client. The server is a web-application server that is provided via Docker, whereas any web-browser can be used as a client to connect to the FICUS/Server. This document describes the setup of the FICUS/Server and FICUS/UI.
There is also the online version of the server available at http://ficus.erams.com with a populated data set for demonstration purpose. However, the online version does not allow the use of local data sets. If you have local FICUS data that you would like to manage and display using the FICUS/UI, you must run the FICUS/Server on your computer.
There are 4 steps required to install and run the FICUS. Step 1 and 2 are one-time installations.
Step 1: Install Docker and Chrome
The FICUS/Server runs as a docker container (http://www.docker.com). Docker is available for Linux, Windows 10, Mac OS/X, and on many cloud environments and Hypervisors. Documentation is available here on how to install and configure Docker for FICUS.
The FICUS/UI works best with Chrome as browser, however, you can use any browser to connect to the FICUS/UI server. You can download Chrome from https://www.google.com/chrome. The Windows PowerShell functions (see step 2) work with chrome.
The document focuses on installing FICUS on Windows 10.
Don't forget to reboot your computer after installing Docker.
Step 2: Download and Install Windows 10 Powershell Functions
On Windows 10 it is recommended to use Powershell functions to manage the FICUS/Server and FICUS/UI.
Start-FicusServer: Starts the Ficus Server
Start-FicusUI: Starts a browser (chrome) and connects to the Ficus Server
Both Functions can be used to run both, Server and UI on the same machine. However, this is not required. You can start the Ficus server on one machine using Start-FicusServer and connect to it from another one using Start-FicusUI -ficushost http://<FicusServer IP>.
Installation of the Ficus Powershell functions is one-time only. It is recommended to install them for the current user. Alternatively, they can be installed system-wide.
Download and unzip FICUS-WPS.zip into your User Documents folder. After unzipping the file you must have a folder WindowsPowerShell folder in your Documents folder. Do not unzip it into a FICUS-WPS folder!
PS C:\Users\joe\Documents> ls
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 3/16/2018 11:11 AM WindowsPowerShell
-a---- 3/16/2018 11:05 AM 3259 FICUS-WPS.zip
Your Ficus functions are now installed. If you type Start-F and press the TAB key, PowerShell should expand the commands.
The Start-FicusServer function will start the Ficus Server with a set of themes. The themes have to be stored on the server's filesystem. The -themesfolder parameter to Start-FicusServer is mandatory. Other parameters as shown below are optional. Use the -? option to get a list of available arguments or use get-help Start-FicusServer -full to list also invocation examples.
If it is not possible to run the FICUS Server using port 80, use the -port parameter to run it on any other available port.
While optional, the -version parameter should be used to switch to different FICUS Server version. If omitted the latest stable major version will be executed. Other versions are available at https://hub.docker.com/r/omslab/ficus-ui/tags.
Ensure the most appropriate version of the FICUS Server is started. As of April 9, 2018, here is information on the following FICUS Server versions. A description of the detailed test of all functionality is available here [URL] .
PS C:\Users\joe\Documents> Start-FicusServer -?
Starts the FICUS Server.
Start-FicusServer [-themesfolder] <String> [[-port] <Int32>] [[-version] <String>] [[-check] <String>] [-grayswan]
Starts the FICUS Server and serves a set of themes.
To see the examples, type: "get-help Start-FicusServer -examples".
For more information, type: "get-help Start-FicusServer -detailed".
For technical information, type: "get-help Start-FicusServer -full".
The Start-FicusUI function will start a chrome browser and connect to the Ficus server. Without any arguments it creates a single window in chrome application mode as the FICUS UI. If provided a -themesfile argument it will load all the themes as listed line by line in this file into separate windows and connects them as brushing session. Furthermore, you can provide the name of the brushing session with the -session argument. Other optional arguments are shown in the help output below. The get-help Start-FicusUI -full command provides all the information about Start-FicusUI
PS C:\Users\joe\Documents> Start-FicusUI -?
Starts the FICUS UI.
Start-FicusUI [[-themesfile] <String>] [[-session] <String>] [[-port] <Int32>] [[-ficushost] <String>] [[-chrome]
Starts the FICUS UI as single window or creates and sets up a brushing session in multiple windows.
Chrome is used as browser.
To see the examples, type: "get-help Start-FicusUI -examples".
For more information, type: "get-help Start-FicusUI -detailed".
For technical information, type: "get-help Start-FicusUI -full".
The Start-TransimsServer function will start the Ficus CSIP server with the transims model service. Use the -? option to get a list of available arguments or use get-help Start-TransimsServer -full to list also invocation examples. Note that this is only needed if you intend to use the transims model service and you do not have an internet connection.
PS C:\> Start-TransimsServer -?
Starts the Transims CSIP server.
Start-TransimsServer [[-version] <String>] [<CommonParameters>]
Starts the Transims CSIP server for running the transims model service locally.
To see the examples, type: "get-help Start-TransimsServer -examples".
For more information, type: "get-help Start-TransimsServer -detailed".
For technical information, type: "get-help Start-TransimsServer -full".
Step 3: Start the FICUS/Server
Execute the following commands on the Powershell command line:
The folder c:\work\ficus has to exist and must contain other folders and subfolders of themes.
The command above will start the server within your terminal. The command above will always use the latest version of the FICUS/UI. It will serve Ficus on port 80.
To use the local folder, e.g. C:\MyFicusThemes containing the framework data, within the FICUS/UI, use the following command. It will also use the latest FICUS/UI version.
PS C:\>Start-FicusServer C:\MyFicusThemes
To download and run a specific version of the FICUS/UI, add the -version flag. This example will run version 0.4.1 of the FICUS/UI. If you want check the list of available versions please visit https://hub.docker.com/r/omslab/ficus-ui/tags
If the command succeeded, you will see the following output (Windows 10 Powershell). If the Server is not installed yet, the Start-FicusServer script will do it.
PS C:\Users\joe\Documents> Start-FicusServer -themesfolder C:\Users\joe\Documents\FicusThemes
latest: Pulling from omslab/ficus-ui
Status: Image is up to date for omslab/ficus-ui:latest
nohup: appending output to 'nohup.out'
nohup: appending output to 'nohup.out'
* Starting Apache httpd web server apache2 AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.17.0.2. Set the 'ServerName' directive globally to suppress this message
You may now connect to http://localhost to run the FICUS UI
The Ficus Server is now ready, you may now use the Start-FicusUI command to connect to it.
You can stop the server by hitting Ctrl+C in the same terminal.
Start-FicusServer can also be used to run error checks on the themes and calculate their gray swan values. Note that the
To perform checks on the theme data, use the following command. It will also use the latest FICUS/UI version.
To calculate gray swan values and store them in each theme's meta.json file, use the following command. Currently the calculation assumes that there is a directory called _meanPop in the top level of the themes folder with a population raster ...PopDenHhold_rzn<nnn>.tif for each realization file.
Step 4.1 Start a FICUS/UI Brushing Session in Batch mode
The Start-FicusUI function can also be used to setup brushing. In a brushing session, a set of FICUS/UI windows show different maps of the same region which are connected to synchronize map extend changes, statistical analysis, and plots. In a brushing session, the interaction of all connected windows are synchronized. In order to simplify and automate the setup of such a session the Start-FicusUI function can be used.
To define the Themes to be shared in brushing, you need to create a text file which lists the theme names to use in each line. A # at the beginning of the line indicates a comment.
The example below shows the file fw.txt containing 3 themes. The file is stored in the Documents folder. The file name is arbitrary.
PS C:\Users\sidereus\Documents> cat fw.txt
# List of themes loaded for brushing
To start the FICUS/UI in brushing mode, use the -themesfile option to pass in the file fw.txt as the brushing config to the Start-FicusUI:
As a result, the function will start 3 FICUS/UI window that are connected within the brushing session named od:
QA/QC of the Framework Themes
It is possible to run a QA/QC check of the themes using the Ficus-Server function. The parameter -check can be used to check the themes data for inconsistencies instead of running the server. The function will print out data problems if they exist. Using this option is recommended before running the server and data changes have been made.
The -check option can take the following arguments:
meta: Checks for present and correct theme meta data.
rasters: Checks for present and correct raster data sets according to naming conventions.
proj: Checks for existing projections all rasters. (This operation can take long to execute!)
all: Checks all the above together.
Note that it is required to also provide the -themesfolder argument with the -check argument.
PS C:\>Start-FicusServer -themesfolder C:\MyFicusThemes -check meta
This will check all themes in C:\MyFicusThemes for correct metadata.
Conventions for Storing FICUS Frameworks
Every framework folder should contain:
a single descriptive index.html file (the FICUS/UI component looks for a single file with .html extension);
a meta.json file for UI customization (see example below).
Underscored directories and ZMiscFiles are not displayed. Only content from quickOverview folder is shown.
The visualization component shows content of quickOverview folder. Five raster maps are expected and displayed in the following order:
meta.json file example
This is a meta.json file example. Keyword meaning:
title:contains the folder name or project title;
order: contains the order with which local folders will be displayed;
classification:contains the palette with which raster maps will be displayed.
"title": "the text that appears in the tree widget",
"order": ["folder1", "folder2", ...],
["#000000", 0, 0.1],
["#001100", 0.1, 0.2],
Listing 1: JSON file prototype
Folder structure example
ExplorerGraph plugin failed: Could not find plugin ExplorerGraph (com.ecyrd.jspwiki.plugin.PluginException:Could not find plugin ExplorerGraph, java.lang.ClassNotFoundException:Class 'ExplorerGraph' not found in search path!)
On linux (and MacOS) you may have to prefix the docker command with sudo.
If you cannot connect to DockerHub, you can also download the docker images directly using these links: erams_db.tgz and erams_web_ficus.tgz. Install them by running the docker load command: