Skip to content

ToolboxInstallation

Jump to bottom Edit New page
Guillaume Galibert edited this page May 31, 2016 · 33 revisions

Toolbox Installation

This page provides an overview of the steps required in order to get the IMOS Toolbox up and running.

Standalone installation

Requirements

  • Windows (either in 32bit or 64bit) or Linux 64bit operating system
  • A relevant Matlab Component Runtime.
  • A deployment database which contains some data (have a look at the deployment database guidelines)
  • Java JRE (1.6 or newer) to be able to query the deployment database with the toolbox.
  • Microsoft Access 32bit if you use a 32bit operating system / Matlab, 64bit if you use a 64bit one (Optional, can be bypassed with UCanAccess, especially when using Linux)

Install Matlab Component Runtime

In order to run the standalone version of the Toolbox, you must first install the Matlab Component Runtime (MCR). You can download the proper MCR installer here :

  • imos-toolbox >= version 2.3 : MCRInstaller_8.0, choose according to your operating system.

You only need to run the installer once. For Windows, it comes as a straightforward executable, for Linux you need to unzip the archive, give executable permissions to the 'install' file and then execute it with root credentials. Then simply follow the instructions. During installation, you might be warned about requiring the .NET Framework - you may safely ignore this warning.

Install IMOS Toolbox

Two options are available:

  • Checkout the 2.5 branch from the GitHub repository:

This option is the best to easily benefit from regular updates and fixes provided for the 2.5 branch. It assumes that you are familiar with using Git and GitHub. Git can easily be installed on Linux, Mac and Windows. Git for Windows comes with Git BASH which provides a BASH environment like in any Linux/Unix/Mac terminal.

In command line, this is how you could set up the 2.5 branch of the toolbox:

cd PATH_TO_WHERE_I_WANT_THE_TOOLBOX/
git clone https://github.com/aodn/imos-toolbox.git
cd imos-toolbox
git checkout 2.5

Now you have a clone of the 2.5 branch of the toolbox and any time there is a critical fix provided with this version, you can benefit from it without affecting you configuration files by just doing:

git pull

If you have created a GitHub account then you can watch the toolbox GitHub repo and be notified about anything that is happening related to the toolbox. This is also how you will be notified of new releases.

Most of the time there shouldn't be any conflict with your configuration files so you can keep your configuration intact across updated sub-versions. See an example of conflict.

  • Download and unzip an archive:

This option is easier but the drawback is that you will have to re-install updated 2.5.x versions and especially port your configuration files from one version to the next manually.

Download the latest release. Most of the users should only use these releases. Archives of the current unstable working copy of the master branch should only be used for test purpose and not in any case to deliver data to AODN. Extract the archive to a directory of your choice.

Configure Deployment Database

Since imos-toolbox version 2.0, in addition to the MS-Access deployment database (template provided in the downloads page), it is also possible to connect to any user-specific database providing its schema complies to a minimum requirements.

Since version 2.5.8, a deployment database in CSV file format is also supported. A template with example entries can be found in the downloads page).

Limitations have been observed such that it is not possible to open the current 32bit version of the deployment database with a Microsoft Access software 64bit. A workaround may be to convert the .mdb to .accdb. Be aware that once you convert to .accdb you cannot go back to .mdb without a fair amount of manual copying to rebuild the .mdb.

MS Access database

The toolbox is able to read the MS Access deployment database using:

  • Microsoft ODBC driver,
  • UCanAccess JDBC driver.
With Microsoft Access ODBC drivers

This solution is only recommended when the architecture version of Microsoft Access matches the one of Matlab or standalone binary architecture. For example if your Microsoft Access software is 32bit but your Matlab is 64bit then this won't work.

Operating system Microsof Access Matlab or standalone binary Compatibility
32bit 32bit 32bit Ok
64bit 32bit 32bit Ok
64bit 32bit 64bit KO
64bit 64bit 32bit KO
64bit 64bit 64bit Ok

The Microsoft Access software comes with a Microsoft Access ODBC driver which can be used to turn your MS Access file into an ODBC source following the described steps below:

  • Start
    • Control Panel
      • Administrative Tools
        • Data Sources (ODBC)
          • User DSN
            • Add
              • Driver: "Microsoft Access Driver (*.mdb)"
              • Data Source Name: "imos-ddb" (or whatever you wish to call it)
              • Select -> navigate to the ddb MS Access file

Once you have configured the ddb as an ODBC source, set the toolbox.ddb property (in toolboxProperties.txt) to the ODBC Data Source Name.

With UCanAccess JDBC drivers

This is the preferred solution for Linux operating systems and when the above solution doesn't work.

Simply set the toolbox.ddb property (in toolboxProperties.txt) to your MS Access file full path.

The main drawback here is the amount of Java Heap memory needed by the Java Virtual Machine and one may face a java.lang.OutOfMemoryError: Java heap space error message. The easiest fix is to tell Java to allocate sufficient heap space memory when the Java Virtual Machine starts up and this can be done in two ways:

  • Add a java.opts file in the root directory of the toolbox, that is to say next to imosToolbox.m, which includes (without the double quotes) : "-Xmx2g". This way we're telling Java to allocate 2Gb of Heap memory. Then start either Matlab or any standalone binary executable from the root directory of the toolbox. This is the preferred method and only available one for use in standalone.
  • For non standalone instalation, in Matlab, via Preferences, in General -> Java Heap Memory and then set it to the maximum (2Gb is a minimum for AIMS database for example).

CSV files

A deployment database template (existing entries are provided as examples) is available here and follows the structure of the MS-Access deployment database schema.

In order to use it with the toolbox one must document the following entries in toolboxProperties.txt:

toolbox.ddb = path_to_the_directory_where_you_keep_the_csv_files

Other database

Your deployment database architecture has to follow a minimum interface requirements to prevent the toolbox from crashing. Then to be able to query it through the toolbox, you must put the driver (.jar file) used to connect to it in the Java directory and set the relevant toolbox.ddb.* properties (in toolboxProperties.txt) properly. Since version 2.5, postgresql-9.4-1201.jdbc4.jar is included by default since Posgresql is used by CSIRO for their deployment database.

Startup

Start the toolbox by double clicking on the relevant executable according to your operating system (if any doubt try Windows 32bit):

  • imosToolbox_Win32.bat for Windows 32bit
  • imosToolbox_Win64.bat for Windows 64bit
  • run ./imosToolbox_Linux64.sh $MCR for Linux 64bit, where $MCR is the deployed MCR root path (e.g. /home/ggalibert/Matlab/MATLAB_Compiler_Runtime/v80/)

This is basically executing the relevant binary for your operating system but then will pause in the command window after exiting the toolbox so that you can have a look at any output message (info, warning or error).

Source installation

Only high level users should be interested in using the source code, for example users who would like to contribute to the development of the code. Users familiar with Git may also be interested in cloning/forking the github repoand then checkout the branch 2.5, this makes contribution to the code easier and it enables them to checkout the current stable version branch and benefit from its maintainance by pulling critical fixes when necessary.

Requirements

  • Windows (either in 32bit or 64bit) or Linux 64bit operating system
  • Matlab (R2012b or newer)
  • A deployment database which contains some data (have a look at the deployment database guidelines)
  • Java JRE (1.6 or newer) to be able to query the deployment database with the toolbox.
  • Microsoft Access 32bit if you use a 32bit operating system / Matlab, 64bit if you use a 64bit one (Optional, can be bypassed with UCanAccess, especially when using Linux)

Download and install

Git fork or clone the GitHub repo and checkout branch 2.5 or download the latest release. Most of the users should only use these releases. Archives of the current unstable working copy of the master branch should only be used for test purpose and not in any case to deliver data to AODN. Extract the archive to a directory of your choice.

Before you can use the toolbox, you must configure the deployment database.

Matlab path

Since version 2.5 there is no need to add the toolbox directory and it sub-directories to the Matlab path. This is automatically done every time you run the toolbox for the current Matlab session. If you plan to switch from one toolbox version to another, you will have to restart Matlab though.

Notes below are for information only, regarding previous versions:

The toolbox root, and every subdirectory within the toolbox root must be on the matlab path. In other words, you must add the following list of directories to your matlab path, either by setting the MATLABPATH environment variable, or, within matlab, using the 'Set Path' dialog, which is accessed via 'File'->'Set Path'.

Assuming that the toolbox is installed in C:\imos-toolbox, you must add the following directories to the path:

  • C:\imos-toolbox\
    • C:\imos-toolbox\AutomaticQC
    • C:\imos-toolbox\DDB
    • C:\imos-toolbox\FlowManager
    • C:\imos-toolbox\GUI
    • C:\imos-toolbox\Graph
      • C:\imos-toolbox\Graph\DepthProfile
      • C:\imos-toolbox\Graph\TimeSeries
      • C:\imos-toolbox\Graph\Transect
    • C:\imos-toolbox\IMOS
    • C:\imos-toolbox\NetCDF
    • C:\imos-toolbox\Parser
    • C:\imos-toolbox\Preprocessing
      • C:\imos-toolbox\Preprocessing\Transform
    • C:\imos-toolbox\Seawater
    • C:\imos-toolbox\Util

Be carefull not to keep links to several different toolbox versions in your Matlab path.

Deployment Database

As with a standalone installation, you must configure your database.

Startup

You should now be able to start Matlab and run the toolbox from its root directory :

>> imosToolbox

You could run it from any directory within Matlab as long as the toolbox's root directory has been added to the Matlab Path. This doesn't work for standalone though.

See the overview on using the toolbox to get started.

Add a custom footer
Add a custom sidebar
Clone this wiki locally