You are not logged in. Click here to log in.

Application Lifecycle Management

Search In Project

Search inClear

FICUS-UI #36086/HEAD / v27917
Tags:  not added yet

FICUS/Server and FICUS/UI

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.

Download Framework Test Data (Optional)

You can download this example framework.

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

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.

  1. 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
    
        Directory: C:\Users\joe\Documents
    
    Mode                LastWriteTime         Length Name
    ----                -------------         ------ ----
    d-----        3/16/2018  11:11 AM                WindowsPowerShell
    -a----        3/16/2018  11:05 AM           3259 FICUS-WPS.zip
    
    PS C:\Users\joe\Documents>
    

  2. Enable the execution of PowerShell commands. Execute the Set-ExecutionPolicy command with the argument Unrestricted. The command below will allow the execution of PS scripts for the current user. (More about the PowerShell's execution policy management can be found at https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-6)
    PS C:\users\joe\Documents> Set-ExecutionPolicy Unrestricted -Scope CurrentUser
    

  3. Install the two Ficus functions with the Import-Module command (Not as Administrator):
    PS C:\Users\joe\Documents> Import-Module Start-FicusServer
    PS C:\Users\joe\Documents> Import-Module Start-FicusUI

Your Ficus functions are now installed. If you type Start-F and press the TAB key, PowerShell should expand the commands.

Function Start-FicusServer

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 -?

NAME
 Start-FicusServer

SYNOPSIS
 Starts the FICUS Server.


SYNTAX
 Start-FicusServer [-themesfolder] <String> [[-port] <Int32>] [[-version] <String>] [[-check] <String>] [-grayswan]
 [<CommonParameters>]


DESCRIPTION
 Starts the FICUS Server and serves a set of themes.


RELATED LINKS

REMARKS
 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".

PS C:\Users\joe\Documents>

Function Start-FicusUI

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 -?

NAME
    Start-FicusUI

SYNOPSIS
    Starts the FICUS UI.


SYNTAX
    Start-FicusUI [[-themesfile] <String>] [[-session] <String>] [[-port] <Int32>] [[-ficushost] <String>] [[-chrome]
    <String>] [<CommonParameters>]


DESCRIPTION
    Starts the FICUS UI as single window or creates and sets up a brushing session in multiple windows.
    Chrome is used as browser.


RELATED LINKS

REMARKS
    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".


PS C:\Users\joe\Documents>

Function Start-TransimsServer

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.

While optional, the -version parameter should be used to switch to different CSIP Transims version. If omitted the latest stable major version will be executed. Other versions are available at https://hub.docker.com/r/omslab/csip-transims/tags.

PS C:\> Start-TransimsServer -?

NAME
    Start-TransimsServer

SYNOPSIS
    Starts the Transims CSIP server.


SYNTAX
    Start-TransimsServer [[-version] <String>] [<CommonParameters>]


DESCRIPTION
    Starts the Transims CSIP server for running the transims model service locally.


RELATED LINKS

REMARKS
    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:

PS C:\Users\joe\Documents> Start-FicusServer -themesfolder c:\work\ficus

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.

Examples

  • 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
     PS C:\>Start-FicusServer -themesfolder C:\MyFicusThemes -version 0.4.1

  • To start the Server and use port 85 instead if 80 use the following command
     PS C:\>Start-FicusServer -themesfolder C:\MyFicusThemes -port 85 

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
Digest: sha256:c6129c80802e989fe6be30218244abc4e5672e9e12455b271b99797a8ed1cf0b
Status: Image is up to date for omslab/ficus-ui:latest
MAPSERVER_PEERS: []
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.
     PS C:\>Start-FicusServer C:\MyFicusThemes -check:all

  • 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.
     PS C:\>Start-FicusServer C:\MyFicusThemes -grayswan

Step 4: Start the FICUS/UI


The command Start-FicusUI will launch a Chrome in application mode and connect to the Ficus Server.

 PS C:\Users\joe> Start-FicusUI
 PS C:\Users\joe>

You should see the FICUS/UI home page now:

ALT_WIKI:%5B!image.png!%5D

The online version of the latest FICUS/UI is available at http://ficus.erams.com.

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
AcademicsC/AFacilitiesI/SchoolOccupationM
TrashC/TCollectionI/GarbageDisposalMannerM
AcademicsC/AServicesI/LiteracyM

PS C:\Users\sidereus\Documents>

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:

PS C:\Users\joe\Documents> Start-FicusUI -themesfile fw.txt -session od
Loading theme: AcademicsC/AFacilitiesI/SchoolOccupationM
Loading theme: TrashC/TCollectionI/GarbageDisposalMannerM
Loading theme: AcademicsC/AServicesI/LiteracyM
PS C:\Users\joe\Documents>

As a result, the function will start 3 FICUS/UI window that are connected within the brushing session named od:

ALT_WIKI:%5B!image1.png!%5D

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.

Example:

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


Folder structure

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.

quickOverview content

The visualization component shows content of quickOverview folder. Five raster maps are expected and displayed in the following order:

  1. name_min.tif
  2. name_1q.tif
  3. name_mean.tif
  4. name_3q.tif
  5. name_max.tif

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.
 1
 2
 3
 4
 5
 6
 7
 8
 9
{
    "title": "the text that appears in the tree widget",
    "order": ["folder1", "folder2", ...],
    "classification": [
        ["#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!)

Notes


  • 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:
    docker load -i erams_db.tgz
    docker load -i erams_web_ficus.tgz

  • You can check the list of running docker containers using
    docker ps -a

  • To check the proper install of the images:
    docker images