test-for-monica.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing MB-System on Ubuntu 14.04 and 16.04 LTS\n",
    "\n",
    "#### Monica Schwehr\n",
    "#### Monterey Bay Aquarium Research Institute  <[email protected]>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**MB-System** is an open source software package for the processing and display of bathymetry and backscatter imagery data derived from multibeam, interferometry, and sidescan sonars. \n",
    "\n",
    "The MB-System website http://www.mbari.org/products/research-software/mb-system/ has installation instructions for building MB-System on MacOS X and Linux. This document will offer a more detailed how-to guide for installing MB-System on Ubuntu 14.04 LTS and 16.04 LTS.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Required Software\n",
    "\n",
    "* GMT 5.2.1 or later\n",
    "    * To get GMT 5.2.1 on Ubuntu 14.04LTS (as of 10/5/16) I had to build from source\n",
    "    * On Ubuntu 16.04LTS, I was able to install via sudo apt-get\n",
    "* GDAL 1.11 or later\n",
    "* NetCDF 3.5.1\n",
    "* Perl 5.x (this has not been tested with Perl 6.0)\n",
    "* Perl Parallel-Forkmanager module\n",
    "* X11\n",
    "* Motif\n",
    "* FFTW\n",
    "* OTPSnc (if you're going to be modeling tidal corrections)\n",
    "* ghostview or gv\n",
    "    * gv is actually a bit more powerful than ghostview and can handle poster-zised images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### UbuntuGIS Repository\n",
    "\n",
    "As of 10/4/16 GMT was not included in the default Ubuntu 14.04 software repository. There is an UbuntuGIS repository (https://wiki.ubuntu.com/UbuntuGIS) that you can add that will bring in tools like GMT, GDAL, MB-System, QGIS, etc. but the versions of the software tools are often a couple iterations behind. When I added this repo to 14.04, the included GMT version was still 5.1. The most recent MB-System requires GMT 5.2.1 or newer.\n",
    "\n",
    "The UbuntuGIS repository is still a great repo to add, as the software included is continuously being added to and updated.\n",
    "\n",
    "To add this repository to your system:\n",
    "     * sudo add-apt-repository ppa:ubuntugis/ppa\n",
    "     * sudo apt-get update\n",
    "     * sudo apt-get upgrade\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing GMT 5.2.1 on Ubuntu 14.04LTS\n",
    "\n",
    "Since the UbuntuGIS repository does not have GMT 5.2.1 as of (10/5/16), we must build from source. This is not as scary as it may sound.\n",
    "\n",
    "#### Software Requirements\n",
    "* Cmake 2.8.5 or later\n",
    "* build-essential\n",
    "* Proj4\n",
    "    * only need development files, but I'd recommend the full package of cartographic projections\n",
    "* NetCDF 4.0 or later\n",
    "* GDAL\n",
    "    * only need development files, but full prog is nice for translating data between different projection outside of GMT\n",
    "* FFTW3\n",
    "    * fast fourier transform library\n",
    "* PCRE \n",
    "    * perl-compatible regular expressions\n",
    "* LAPACK\n",
    "    * linear algebra tool pack\n",
    "    \n",
    "    \n",
    "*This list is not exhaustive, and you may need more or less programs and libraries depending on your current linux configuration and any previously installed software. Any missing tools will be identified during the build process*\n",
    "\n",
    "\n",
    "** We can install these dependencies all in one go via the command:**\n",
    "___________________________________________________________\n",
    "    sudo apt-get install build-essential cmake libnetcdf-dev libgdal-bin gdal-bin libfftw3-dev libpcre3-dev liblapack-dev libproj-dev proj-bin\n",
    "___________________________________________________________ "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "** Download GMT 5.2.1 (or later)**\n",
    "\n",
    "1. Go to: http://gmt.soest.hawaii.edu/projects/gmt/wiki/Download\n",
    "+ You'll need:\n",
    "    + gmt-5.2.1-src.tar.gz\n",
    "    + gshhg-gmt-2.3.6.tar.gz - Global Self-consistent Hierarchical High-resolution Geography\n",
    "    + dcw-gmt-1.1.2.tar.gz - country polygons\n",
    "+ cd to directory and before unpacking, verify downloand integrity with the checksum if you like\n",
    "    + md5sum gmt-5.2.1-src.tar.gz\n",
    "    + should return: df96d3cc9a93bc3c049f1523ada57117\n",
    "+ tar -xf gmt-5.2.1-src.tar.gz\n",
    "+ you'll also need to unpack the gshhg and dwg files somewhere. \n",
    "    + When installing via a package manager, GMT places them in /usr/share/\n",
    "    + you may want to pick a location outside of /usr/ such as your home directory\n",
    "+ cd into the unpacked gmt-5.2.1 directory\n",
    "+ cd in cmake\n",
    "+ cp ConfigUserTemplate.cmake ConfigUser.cmake\n",
    "    + edit ConfigUser.cmake to tell GMT where to install and where the geography data is\n",
    "        + set (CMAKE_INSTALL_PREFIX <path to install gmt>)\n",
    "            + do not edit this line if you want gmt to install into the default directory structure\n",
    "                + On 14.04 I think this is /usr/bin/\n",
    "        + set (GSHHG_ROOT <path to gshhg>)\n",
    "            + example: set (GSHHG_ROOT /usr/share/gmt-gshhg)\n",
    "        + set (DCW_ROOT <path to dcw>)\n",
    "+ cd out of make, so you are in gmt-5.2.1:\n",
    "+ run the following:\n",
    "    + mkdir build\n",
    "    + cd build\n",
    "    + cmake ..\n",
    "    + make\n",
    "    + sudo make install\n",
    "        + if you are building outside of /usr/ I think you can run this without the sudo command\n",
    "\n",
    "** Remember: If you installed GMT outside of the default directory, you'll want to add it to your path in your .bashrc or .bash_profile **\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Installing GMT 5.2.1+ on Ubuntu 16.04LTS\n",
    "\n",
    "In Ubuntu 16.04LTS you can install GMT 5.2.1 directly by adding unstable repository of UbuntuGIS for Xenial\n",
    "\n",
    "__________________________________\n",
    "    sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable\n",
    "    sudo apt-get update\n",
    "    sudo apt-get install gmt\n",
    "______________________________________________ \n",
    "\n",
    "This *might* work on Ubuntu 14.04, at time I was installing on 14.04, I did not know about this repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Let's test our GMT install\n",
    "\n",
    "----\n",
    "    gmt pscoast -R-130/-30/-50/50 -Jm0.025i -B30g30:.Mercator: -Di -W > mercator.ps\n",
    "    gv mercator.ps\n",
    "----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you run the above cell, you should end up with map centered on th equator showing parts of North and South America"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " <img src=\"mercator.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The rest  of the MB-System requirements can be installed in one line\n",
    "\n",
    "-------     \n",
    "     sudo apt-get install libx11-dev xorg-dev libmotif-dev libmotif4 libxp-dev mesa-common-dev libsdl1.2-dev libsdl-image1.2-dev build-essential gfortran nautilus-open-terminal libfftw3-3 libfftw3-dev libnetcdf-dev netcdf-bin libgdal-bin gdal-dev gv csh libgmt-dev libproj-dev\n",
    "---------\n",
    "\n",
    "**NOTE:** to install libmotif4 in 16.04, I needed to add the ubuntu extras repo\n",
    "\t* sudo su\n",
    "\t* echo 'deb http://cz.archive.ubuntu.com/ubuntu trusty main universe' >> /etc/apt/sources.list.d/extra.list\n",
    "\t* apt-get install update\n",
    "    * sudo apt-get install libmotif4 bmotif-dev"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Now, for MB-System itself:\n",
    "\t\n",
    "These steps assume you have downloaded a tar.gz file from the website: http://www.mbari.org/products/research-software/mb-system/\n",
    "\n",
    "The steps are the same whether you're on 14.04LTS or 16.04LTS\n",
    "\n",
    "-----\n",
    "     * unpack directory (tar -xf xxx.tar.gz), and cd into it\n",
    "     * type ./configure at prompt\n",
    "-----\n",
    "\n",
    "If you are still missing any major packages, configure will let you know\n",
    "\n",
    "If you want to install into a specific directory (I do this because I test multiple versions), add the prefix option: \n",
    "\n",
    "-----\n",
    "    ./configure --prefix=/home/mschwehr/mb-system-5.5.2279)\n",
    "-----\n",
    "\n",
    "Run make\n",
    "   make ensures it can find all the necessary libraries, so it is possible to get make errors complaining about missing libraries even if configure passes, most missing libraries can be installed with sudo apt-get install\n",
    "`<name of library>`. \n",
    "\n",
    "Once make succeeds, you then run the actual install\n",
    "\n",
    "-----\n",
    "    make\n",
    "    sudo make install\n",
    "-----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Lets Test the install\n",
    "\n",
    "-----\n",
    "    mbgrdviz\n",
    "-----\n",
    "\n",
    "Should bring up the MB-System grid visualization tool.\n",
    "Click on Help --> About and you should see the version number"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<img src=\"mbgrdviz_about.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Now to set our GMT configure file\n",
    "\n",
    "The main difference between GMT 4 and GMT 5 is that in version 5, a lot of the tools have been rewritten as modules. This is why in out GMT test above we had to type \"gmt pscoast\" instead of just the command \"pscoast.\"\n",
    "\n",
    "The affects the way some MB-System commands that include calls to GMT commands (such as mbcontour & mbswath) function. Therefore, we need to set up our gmt-config file.\n",
    "\n",
    "The necessary MB-System library that we need to make GMT aware of (mbsystem.so) is in the MB-System install directory, under the lib subdirectory.\n",
    "\n",
    "Run the command gmtset from your home directory to copy over the default gmt.conf file:\n",
    "\n",
    "-----\n",
    "    gmt gmtset  GMT_CUSTOM_LIBS   /path/to/MB-Sys/install/lib/mbsystem.so \n",
    "-----\n",
    "\n",
    "So for me, I installed MB-Sys in my home directory, not usr/local/ because I have multiple versions on my machine.\n",
    "The above command for me would look like:\n",
    "\n",
    "\n",
    "-----\n",
    "    gmt gmtset  GMT_CUSTOM_LIBS   /home/mschwehr/MB-Sys-552282/lib/mbsystem.so \n",
    "-----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## If you encounter problems\n",
    "\n",
    "1) You get hung up processes running certain commands that automatically open ghostview or an image viewer, (e.g: mbm_plot runs, but running the resulting .cmd file hangs) make sure your mbdefaults are set for postscript viewer and screen image viewer:\n",
    "\n",
    "------\n",
    "    Set the postscript viewer using\n",
    "\n",
    "        mbdefaults -Dgv -V\n",
    "\n",
    "    Set your favorite screen image viewer (e.g. feh) using\n",
    "\n",
    "        mbdefaults -Ifeh -V\n",
    "-----\n",
    "\n",
    "2) You get a shared library file error trying to run MB-Sys commands: \"mbgrdviz: error while loading shared libraries: libmbio.so.0: cannot open shared object file: No such file or directory >\" \n",
    "\n",
    "This can happen if you installed MB-Sys in a location other than the default (you used --prefix= when you ran ./configure)\n",
    "\n",
    "libmbio.so should be located in your MB-Sys install directory, under the lib subdirectory \n",
    "\n",
    "To define the path to the shared libraries directory:\n",
    "\n",
    "-----\n",
    "    LD_LIBRARY_PATH=/home/mschwehr/MB-Sys-5.5.2282/lib/ \n",
    "    export LD_LIBRARY_PATH\n",
    "-----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### So now you should be good to go with MB-System on your Ubuntu system.\n",
    "\n",
    "I'll make another post and upload some test data soon, so we can run through some of the basic MB-System commands and you can compare your results to mine to test for consistency. "
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Bash",
   "language": "bash",
   "name": "bash"
  },
  "language_info": {
   "codemirror_mode": "shell",
   "file_extension": ".sh",
   "mimetype": "text/x-sh",
   "name": "bash"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}