Skip to content

ToolboxInstallation

Jump to bottom Edit New page
Guillaume Galibert edited this page Feb 15, 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

Download an archive from the downloads page. Most of the users should only use the last stable version : imos-toolbox-X.XX.zip. Unstable versions YY-MM-DD_unstable_snapshot.zip should be used for test purpose only and not in any case to deliver data to eMII. Extract the archive to a directory of your choice.

Configure Deployment Database

Since imos-toolbox versions 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.

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 of version lower than 2013. It is possible to open it with Office 64bit 2013 though.

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).

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 the github repo, 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

Download an archive from the downloads page. Most of the users should only use the last stable version : imos-toolbox-X.XX.zip. Unstable versions YY-MM-DD_unstable_snapshot.zip should be used for test purpose only and not in any case to deliver data to eMII. Extract the archive to a directory of your choice.

Before you can use the toolbox, you must configure the deployment database. 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 change from one toolbox version to another, you will have to restart Matlab though.

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