-
Notifications
You must be signed in to change notification settings - Fork 31
ToolboxInstallation
This page provides an overview of the steps required in order to get the IMOS Toolbox up and running.
- 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)
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.
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. Itassumes 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.5Now 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 pullIf 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.
To give you an example in case there is a conflict with one file this is what it could look like:
git pull
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5 (delta 1), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (5/5), done.
From https://github.com/aodn/imos-toolbox
af92a16..c1187a6 2.5 -> origin/2.5
b46e023..d598814 master -> origin/master
* [new tag] v2.5.6 -> v2.5.6
Updating 6baa8f3..c1187a6
error: Your local changes to the following files would be overwritten by merge:
toolboxProperties.txt
Please, commit your changes or stash them before you can merge.
Abortingthen I recommend you create a new branch to which you will commit your changes responsible for conflicts:
git checkout -b MY_NEW_BRANCH
git add toolboxProperties.txt
git commit -m 'conflicting files'Let's go back to branch 2.5, we should now be able to pull updates:
git checkout 2.5
git pullNow let's have a look at the nature of the conflicts one file at a time:
git diff MY_NEW_BRANCH..2.5 -- toolboxProperties.txt
diff --git a/toolboxProperties.txt b/toolboxProperties.txt
index 5d77349..bf710d5 100644
--- a/toolboxProperties.txt
+++ b/toolboxProperties.txt
@@ -1,6 +1,6 @@
% filename or ODBC DSN of MS-ACCESS deployment database
% ex. : /home/ggalibert/OceanDB.mdb or imos-ddb
-toolbox.ddb = /home/ggalibert/OceanDB.mdb
+toolbox.ddb =
% or full connection details to other kind of deployment database :
% class name of JDBC database driver
@@ -91,3 +91,12 @@ saveGraph.imgType = png
% visual QC plots export properties
visualQC.export = true
visualQC.fastScatter = true
+
+% default nonspecialized scalar colormap and number of colour steps
+% jet | parula | viridis
+visualQC.defaultColormap = parula
+visualQC.ncolors = 64
+
+% simple zbuffering of markers if using fallback fastScatterMesh plot (fastScatter = false)
+% 'ascending', 'descending', 'triangle', 'vee', 'flat', 'parabolic', 'hamming', 'hann'
+visualQC.zbuffer = triangleThe first change is my path to my deployment database which has been reset. This was the conflict and I want to keep this local change so I should open toolboxProperties.txt and document the path to my deployment database back in it. I can see that my new version of toolboxProperties.txt includes some new entries that doesn't impact any of my existing personal changes so I can leave them.
Of course if your conflicts involve more than one file then you would need to fix them one after the other.
I can now delete my temporary MY_NEW_BRANCH branch:
git branch -D MY_NEW_BRANCH- 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 eMII. Extract the archive to a directory of your choice.
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.5, 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.
The toolbox is able to read the MS Access deployment database using:
- Microsoft ODBC driver,
- UCanAccess JDBC driver.
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
- Driver: "Microsoft Access Driver (
- Add
- User DSN
- Data Sources (ODBC)
- Administrative Tools
- Control Panel
Once you have configured the ddb as an ODBC source, set the toolbox.ddb property (in toolboxProperties.txt) to the ODBC Data Source Name.
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).
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.
Start the toolbox by double clicking on the relevant executable according to your operating system (if any doubt try Windows 32bit):
-
imosToolbox_Win32.batfor Windows 32bit -
imosToolbox_Win64.batfor Windows 64bit - run
./imosToolbox_Linux64.sh $MCRfor 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).
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.
- 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)
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 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 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\AutomaticQCC:\imos-toolbox\DDBC:\imos-toolbox\FlowManagerC:\imos-toolbox\GUI-
C:\imos-toolbox\GraphC:\imos-toolbox\Graph\DepthProfileC:\imos-toolbox\Graph\TimeSeriesC:\imos-toolbox\Graph\Transect
C:\imos-toolbox\IMOSC:\imos-toolbox\NetCDFC:\imos-toolbox\Parser-
C:\imos-toolbox\PreprocessingC:\imos-toolbox\Preprocessing\Transform
C:\imos-toolbox\SeawaterC:\imos-toolbox\Util
Be carefull not to keep links to several different toolbox versions in your Matlab path.
As with a standalone installation, you must configure your database.
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.