Author: David Caress, Dale Chayes
Description: open source software for processing bathymetry and backscatter data from multibeam and sidescan sonar
Keywords: seafloor,mapping,multibeam,sonar,bathymetry,sidescan,swath processing,open,source,software

  How to Get and Install MB-System

- How to get the MB-System source distribution
- Access MB-System source version control system
- Packaged MB-System distributions
- Other required and suggested software and data
- How to unpack an MB-System source code distribution
- How to install MB-System using the configure script
- How to install MB-System using the install_makefiles script

  How to Get The MB-System Source Distribution

The source code for MB-System is available as a compressed tar archive by anonymous ftp to the Lamont-Doherty Earth Observatory of Columbia University. This archive file is about 3 megabytes in size and, depending on the speed of your internet connection, may take a few minutes to transfer.

Click here to ftp the current MB-System release as a compressed tar archive.

Click here to get point-and-click ftp access to all of the MB-System related files available from Lamont (these may include data examples and beta distributions of MB-System ).

If access through the above links fails, try running ftp from a terminal shell. The following commands represent a typical anonymous ftp session (note that your@email.address literally means to enter your email address, and that many modern ftp clients do not require the "binary" command).

% ftp ftp.ldeo.columbia.edu
Name: anonymous
Password: your@email.address
> cd pub/MB-System
> binary
> get MB-System.tar.gz
> quit

If anonymous ftp fails with an error message like: "Sorry no DNS entry" after the email address is entered as the anonymous password, this means that the internet address (also called IP address) of the computer in use is not known to the Lamont network to be legitimate. As a security measure, illegitimate IP addresses are not allowed to connect to the Lamont network. The Lamont ftp server attempts to look up or resolve IP addresses using the primary Domain Name Service (DNS) servers associated with the internet as a whole. So, this problem arises when computers use IP addresses are not properly registered with the global DNS servers. This situation sometimes exists for computers connecting through improperly configured firewalls or Network Address Translation (NAT) devices. Users facing this issue can often succeed by running ftp from a "better connected" server in their organization. Otherwise, they will need to contact their internet service provider or their network/computing support staff.

Access MB-System Source Version Control System

The MB-System source code is archived and managed using Subversion, an open source version control system. The MB-System and MB-Cookbook Subversion repositories can be browsed through a web interface at:
  http://svn.ilab.ldeo.columbia.edu/
The MB-System repository is at:
  http://svn.ilab.ldeo.columbia.edu/listing.php?repname=MB-System
The entire repository, or individual files, can be downloaded through this web interface. Clicking the the link above to bring up the WebSVN interface showing the most recent revision to the MB-System code base, along with a list of paths including "branches", "tags", and "trunk". To download the entire code base, click on the "Download" link to the right of "trunk". To browse the structure and download individual files, click on the "trunk" link. Users can build MB-System using this downloaded code base, but should note that the repository stores a number of files that are not included in the MB-System distributions.

Packaged MB-System Distributions

MB-System is included in Poseidon Linux, the "Scientific GNU/Linux". Poseidon is an Ubuntu Linux based distribution including a selection of open source software packages intended to support scientific research. In particular, it offers several specific tools in the areas of GIS, 3D Visualization, Mathematics, Statistics and several other fields of research.

MB-System has been packaged for MacOS X as part of the Fink Project. The MB-System Fink package can be found at:

  http://pdb.finkproject.org/pdb/package.php/mbsystem

MB-System has also been packaged for MacOs X as part of Homebrew. If you have Homebrew installed, then MB-System and its prerequisites can be installed using these two commands:

  brew tap homebrew/science
  brew install mbsystem

The OSGeo-Live distribution includes MB-System. OSGeo-Live is a self-contained bootable DVD, USB thumb drive or Virtual Machine based on Xubuntu that includes a wide variety of open source geospatial software.

The Scripps Institution of Oceanography's Shipboard Technical Support group maintains a repository of open source software RPM distributions for Red Hat Enterprise Linux and CentOS Linux. This repository includes both source and binary distributions of MB-System, GMT, and netCDF that can be accessed using the yum utility. The MB-System RPMs require the GMT and netCDF RPMs, but have no other external dependencies. This repository can be found at:

http://sts.ucsd.edu/repos/centos-5/local

The SIO-STS gpg signing key is

http://sts.ucsd.edu/repos/centos-5/local/RPM-GPG-KEY-STS

Thanks to Christian Ferreira for creating and distributing Poseidon Linux, to Kurt Schwehr for maintaing the Fink MB-System package, to Anthony Lukach for maintaining the Homebrew MB-System package, to Hamish Bowman for maintaining the OSGeo-Live MB-System package, and to Frank Delahoyde for maintaining the CentOS MB-System RPM distribution.

  Other Required and Suggested Software and Data

MB-System requires a number of other software packages and databases to be fully functional. These are:

- GMT version 4.5 or later: MB-System makes use of the Generic Mapping Tools (GMT) libraries and programs for much of its graphics. GMT also includes a detailed global coastline database. GMT has been developed by Professor Paul Wessel of SOEST (School of Ocean and Earth Science and Technology at the Univeristy of Hawaii) and Dr. Walter H. F. Smith of NOAA. The GMT source code is available from the GMT web page.
- NetCDF version 3.5.1 or later: Both GMT and MB-System require the NCAR netCDF library.
- Perl version 5.0 or later: Perl is a fast, well documented scripting language used widely in the Linux/Unix world. MB-System contains a number of perl scripts used both for installation and to ease common tasks. Most of the current Unix operating systems include perl. If you need to obtain the perl source code, first check with your local system administrator - you will probably find perl already available locally. The perl source code can be obtained from the GNU software archives of the Free Software Foundation.
- Perl Parallel-Forkmanager module: this Perl module is required for the parallel processing macros mbm_multicopy, mbm_multidatalist, and mbm_multiprocess to work. An easily installed package is available from from www.cpan.org.
- X11: The interactive graphical utilities in MB-System (MBedit, MBnavedit, MBvelocitytool, MBgrdviz, MBeditviz) use and require the X11 windowing system.
- Motif: The interactive graphical utilities in MB-System (MBedit, MBnavedit, MBvelocitytool, MBgrdviz, MBeditviz) use version 2 of the Motif widget set, and Motif libraries are required for these utilities to be built and to run. Most current Unix/Linux operating systems include the required Motif libraries, either in the original proprietary form (Motif), or the not-quite-open-source form (OpenMotif). If you do not have these libraries, the OpenMotif 2 source is available through Motifzone. An old alternative open source Motif-compatible distribution called LessTif does not work with the new OpenGL based MB-System programs (MBgrdviz, MBeditviz) and should be avoided.
- Levitus Database: The MB-System program mblevitus depends on a 16 MByte data file that is not included in the MB-System tarfile. Click here to ftp this file. Be sure to uncompress the file and to set the "LEVITUS" flag in the install_makefiles appropriately, as described below in the installation section.
- FFTW: The "Fastest Fourier Transform in the West" package is used by the sonagram calculation program MBbsegypsd to calculate, well, Fast Fourier Transforms. FFTW is commonly used and thus available on or for most current Unix operating systems.
- OTPSnc: The Oregon State Ocean Tide Prediction Software package is required for the tidal modeling program MBotps (which in fact is just a convenient front end for the old-style-batch interface of OTPS). The OTPSnc package can be obtained from the tidal modeling group at Oregon State University.

MB-System produces Postscript based graphics. Most current Unix operating systems provide a program which serves as a screen-based Postscript viewer. If you do not have a Postscript viewer, one option is to obtain one of several Ghostscript-based packages from the Free Software Foundation.

- ghostview: Open source screen Postscript viewer. The source code can be obtained from the GNU software archives of the Free Software Foundation.

- gv: Open source screen Postscript viewer. This package is a bit more sophisticated than ghostview and can handle poster-sized plots. The source code can be obtained from the GNU software archives of the Free Software Foundation.

Users of MacOs X should note that many of the above packages can be painlessly installed using the fink package available from the Fink Project.

How to Unpack an MB-System Source Code Distribution

The MB-System source code is extracted from the distribution using the tar utility:

    tar xvzf MB-System.tar.gz

or for some older systems with feature-limited versions of tar, a combination of gunzip and tar:

    gunzip MB-System.tar.gz
    tar xvf MB-System.tar

This will create a directory called (for the 5.4.2035 distribution):

    mbsystem-5.4.2136

In order to build and install MB-System from an interactive shell, you need to change your current directory to the distribution:

    cd mbsystem-5.4.2136

How to Install MB-System Using the Configure Script

The configure script has been generated using the autoconf package. The current configure script does not resolve all of the flags and locations needed to build MB-System on all platforms, but does allow for flexible installation and generation and use of shared libraries without requiring interactive editing. These improvements make MB-System distributions much more amenable to inclusion in package manager systems like Debian and Fink. We hope to improve the configure script so that less intervention is required.

The basic steps for building MB-System using the configure script are:

1. Move to the top of the MB-System distribution directory:

cd mbsystem-5.4.2176

2. Run the configure script to generate the Makefile files throughout the distribution directory structure. The command line options for configure are discussed below.

[...pre-options...]./configure [...options...]

3. Run the make utility to build the software within the source distribution.

make

4. Run the make utility with the install option to install the software within the target location that was specified while running configure. This step copies the libraries, programs, scripts, manual pages, and web pages to the target destinations.

make install

The configure script is intended to discern the enviroment, locate prerequisite packages, and construct the makefiles with a minimum of user intervention. In practice, users generally need to set at least some options when using the configure script in order to successfully build, install, and run MB-System. If NetCDF and GMT installations cannot be located, MB-System cannot be built. If FFTW3, Motif, or OpenGL cannot be found MB-System will be built, but without the applications that depend on these packages.

Depending on how user permissions are set on your system and where the package is to be installed, it may be necessary to execute some or all of the above commands with superuser privileges. On older styles of Unix and Linux, this was typically accomplished by using the su command to become root, or superuser, a step that requires knowing the root password for the system. Following a successful invocation of su in a command shell, all commands have superuser privileges. On MacOsX and other "modern" flavors of Unix and Linux, it's more common to use the sudo command in front of other commands in order to execute them with superuser privileges. An administrator password is required for the first instance of sudo, but not for subsequent instances (at least for a period of time, typically five minutes). In this case, the commands become:

    sudo ./configure
    sudo make
    sudo make install

The default destination is /usr/local, and so one should find the MB-System executable programs and scripts in /usr/local/bin, the shared libraries in /usr/local/lib, the manual pages in /usr/local/man, and the projection and Levitus databases accessed by MB-System in /usr/local/share/mbsystem. However, one can control the installation destination of the configure script on the command line by using a "--prefix" argument. For example, to install MB-System into /Users/caress/sandbox/mbsystem, you can use:

    sudo ./configure \
    --prefix=/Users/caress/sandbox/mbsystem

The complete list of configure's installation location options is:

    --prefix 				This is the common installation prefix for all files.
     						If exec_prefix is defined to a different value, prefix
     						is used only for architecture-independent files.
     						[Default: /usr/local]
    --exec_prefix 			The installation prefix for architecture-dependent files.
    						By default it's the same as prefix. You should avoid
    						installing anything directly to exec_prefix. However,
    						the default value for directories containing
    						architecture-dependent files should be relative to
    						exec_prefix.
    						[Default: ${prefix} ==> /usr/local]
    --datarootdir 			The root of the directory tree for read-only architecture
    						-independent data files.
    						[Default: ${exec_prefix}/share ==> /usr/local/share]
    --bindir 				The directory for installing executables that users run.
    						[Default: ${exec_prefix}/bin ==> /usr/local/bin]
    --libdir 				The directory for installing object code libraries.
    						[Default: ${exec_prefix}/lib ==> /usr/local/lib]
    --includedir 			The directory for installing C header files.
    						[Default: ${exec_prefix}/include ==> /usr/local/include]

MB-System depends on librarys from a number of different packages, including NetCDF, GMT, FFTW3, X11, and Motif. Sometimes a user will have more than one installation of a package available, and specifying which is used is desirable. Also, unfortunately the configure script does not always successfully find all needed packages. Consequently, the configure script allows users to set the locations on the command line when necessary. The configure command line options controlling the locations of prerequisites are:

    --with-netcdf-lib 		Location of NetCDF libs
    --with-netcdf-include 	Location of NetCDF headers
    --with-gmt-lib 		Location of GMT libs
    --with-gmt-include 	Location of GMT headers
    --with-fftw-lib 		Location of FFTW3 libs (optional)
    --with-fftw-include 	Location of FFTW3 headers (optional)
    --with-motif-lib 		Location of Motif libs (optional)
    --with-motif-include 	Location of Motif headers (optional)
    --with-opengl-lib 		Location of OpenGL libs (optional)
    --with-opengl-include 	Location of OpenGL headers (optional)
    --with-otps-dir		Location of OTPS installation (optional)

The MB-System distribution includes the source code for the GSF and the PROJ4 packages. By default, the configure script seeks to build the GSF library as libmbgsf and seeks to link with a libproj built external to MB-System. Configure accepts commands to build MB-System without GSF or to use the included PROJ4 source.

    --without-gsf			Build without including or supporting GSF
    						The default is to build the bundled
    						gsf library as libmbgsf and link with it
    --enable-bundledproj	Build using bundled proj package - the
    						default is to link with libproj

Note that specification of FFTW3, Motif, and OpenGL is optional. If the configure script does not find these packages and the user does not specify their locations, then some MB-System programs will not be built. Lack of FFTW3 means that mbsegypsd is not built. No OpenGL results in the visualization programs mbgrdviz and mbeditviz not being built. Lack of Motif means that no graphical programs of any type are built.

Mac OS X

Many MacOsX users have their NetCDF, GMT, FFTW3, and OpenMotif installations through the Fink package manager, which installs packages in /sw. The configure script fails to find packages in /sw, and so the user must explicitly specify those packages. The OTPS tide modeling software used by mbotps is not packaged in Fink, and so must be manually installed by a user if mbotps is to work correctly. Installation of MB-System on a Mac running MacOsX 10.9 will likely use a configure command that looks something like:

    sudo CFLAGS="-I/opt/X11/include -L/opt/X11/lib" \
    ./configure \
        --with-netcdf-include=/sw/include \
        --with-netcdf-lib=/sw/lib \
        --with-gmt-include=/sw/include \
        --with-gmt-lib=/sw/lib \
        --with-proj-include=/sw/include \
        --with-proj-lib=/sw/lib \
        --with-fftw-include=/sw/include \
        --with-fftw-lib=/sw/lib \
        --with-motif-include=/sw/include \
        --with-motif-lib=/sw/lib \
        --with-otps-dir=/usr/local/tides/OTPS2

As shown here, one can also add to the commands seen by the compiler ("CFLAGS") and linker ("LDFLAGS") if desired or necessary by prefacing the configure command with arguments setting the environment variables CFLAGS and LDFLAGS. Here the current location of X11 header files and libraries must be specified because the new (to MacOsX) location of X11 in /opt is not known to the configure script. Another example is that in order to compile MB-System for user with a debugger, all compiler commands must include the "-g" argument. So, to enable use of the gdb debugger, the configure command becomes:

    sudo CFLAGS="-g -I/opt/X11/include -L/opt/X11/lib" \
    ./configure \
        --with-netcdf-include=/sw/include \
        --with-netcdf-lib=/sw/lib \
        --with-gmt-include=/sw/include \
        --with-gmt-lib=/sw/lib \
        --with-proj-include=/sw/include \
        --with-proj-lib=/sw/lib \
        --with-fftw-include=/sw/include \
        --with-fftw-lib=/sw/lib \
        --with-motif-include=/sw/include \
        --with-motif-lib=/sw/lib \
        --with-otps-dir=/usr/local/tides/OTPS2

Ubuntu Linux

For Ubuntu Linux 12.04.02LTS, the following use of the apt-get utility will install all of the MB-System prerequisites excepting OTPS:

    sudo apt-get install 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 gdal-bin gdal1-dev gmt libgmt-dev gv

Because GMT is installed in an unusual way on Ubuntu, it is necessary to augment the PATH and LD_LIBRARY_PATH environment variables by adding the following two lines to each user's ~/.bashrc file:

    export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
    export PATH=/usr/lib/gmt/bin:$PATH

By default, the Ubuntu GMT installation is not known to pkg-config, and the installation points of the libraries and the header files must be specified:

    sudo ./configure --prefix=/usr/local \
        --with-gmt-include=/usr/include/gmt \
        --with-gmt-lib=/usr/lib

Although the GMT installation does not include a pkg-config *.pc file, it is simple to construct one. On Ubuntu pkg-config looks in /usr/lib/pkgconfig, so one can put a file there called gmt.pc with the contents:

    # start gmt.pc
    prefix=/usr
    exec_prefix=${prefix}
    libdir=${exec_prefix}/lib
    includedir=${prefix}/include/gmt
    ccompiler=gcc
    cppcompiler=g++

    Name: gmt
    Description: GMT Libraries
    Version: 4.5.6
    Libs: -L${libdir} -lgmt -lgmtps -lpsl
    Cflags: -I${includedir}
    # end gmt.pc

If the GMT installation has been augmented with a /usr/lib/pkgconfig/gmt.pc file so that pkg-config knows about GMT, then the configure call to install in /usr/local is just:

    sudo ./configure

CentOs or Red Hat Linux

The package manager usually used on CentOs or Red Hat Linux systems is yum. To install all of the MB-System prerequisites use the command:

    sudo yum install openmotif openmotif-devel fftw fftw-devel netcdf netcdf-devel \
    		proj proj-devel gdal-devel gmt gmt-devel gv nedit

If the prerequisites have all been installed with yum and it is desired to install MB-System in /usr/local, then only a simple call to configure is required:

    sudo ./configure

How to Install MB-System Using the Install_makefiles Script

For over two decades, the only means to build MB-System distributions was a crude Perl script called install_makefiles that needed to be edited to set the operating system and the locations of prerequisite packages. Although a autoconf-type configure script is now provided, as described above, the old install_makefiles script is still included in the MB-System distribution and remains an alternative means to build and install MB-System.

In order to use this alternative build system, you must edit the perl script mbsystem/install_makefiles, and set a number of parameters to reflect the system architecture, the location of the installation, and the locations of certain required libraries. This script will read template makefiles in the MB-System source directories and create makefiles with the correct dependencies, compile flags, and link flags. The important parameters to be set in install_makefiles are listed below. The install_makefiles script includes comments suggesting parameters to use for many common computer systems.

These parameters must be set for all installations:

- MBSYSTEM_HOME - Absolute path to the directory containing install_makefiles.
- OS - Operating system (Recognized options are: DARWIN, LINUX, CYGWIN, SUN, IRIX, IRIX64, SOLARIS, HPUX, LYNX, CYGWIN or OTHER).
- CFLAGS - Compile flags for C source files. These vary with different operating systems and installations.
- LFLAGS - Load flags for all object files.
- NETCDFLIBDIR - Location of NetCDF library libnetcdf.a
- NETCDFINCDIR - Location of NetCDF include file netcdf.h
- GMTLIBDIR- Location of GMT libraries libgmt.a and libpsl.a
- GMTINCDIR - Location of GMT include files gmt.h, grd.h, and pslib.h
- LEVITUS - Path of Levitus global water properties data file. This is usually $MBSYSTEM_HOME/share/annual.
- PROJECTIONS - Path of PROJ4 projections database. This is usually $MBSYSTEM_HOME/share/Projections.dat.

These two parameters are required to build the graphical tools mbedit, mbnavedit, mbvelocitytool, mbnavadjust, mbgrdviz, and mbeditviz. If these parameters are not both set, no graphical tools will be built.

- MOTIFINCDIR - Location of Motif include files.
- MOTIFLIBS - X11 and Motif libraries required for graphical tools.

This parameter must be set to build the openGL tools mbgrdviz and mbeditviz:

- OPENGLLIBS - OpenGL libraries required for new graphical tools, including mbgrdviz and mbeditviz. If this parameter is not set, mbgrdviz and mbeditviz will not be built

This parameter must be set to build the sonogram calculation program mbsegypsd:

- FFTWLIBDIR - location of FFTW library providing fast Fourier transform.
- FFTWINCDIR - location of FFTW include files

This parameter must be set for the tidal modeling program mbotps to work:

- OTPSDIR - location of OTPSnc tide prediction program predict_tide.

This optional parameter can be used to specify a non-default C compiler:

- CC - C compiler to be used.

These optional parameters can be used to specify linking with an independent installation of the PROJ4 library. In this case, the PROJ4 library included with MB-System will not be built.

- PROJLIB - Path to PROJ4 library (usually libproj.a)
- PROJINCDIR - Location of PROJ4 include file proj_api.h

These optional parameters can be used to specify linking with an independent installation of the GSF library. In this case, the GSF library included with MB-System will not be built.

- GSFLIB - Path to GSF library (usually libgsf.a)
- GSFINCDIR - Location of GSF include file gsf.h

To execute install_makefiles, do the following:

    % cd mbsystem-5.3.1955

    % install_makefiles

Because install_makefiles is a perl script, the executable perl must be available in the installer's path. Once install_makefiles has been correctly configured and run, give the command "make all" to generate the executable programs:

    % make all

The make command will descend recursively down through the directory structure, compiling source files, linking object files, and copying executables and manual pages to the appropriate directories. The executables will be placed in mbsystem-5.1.3/bin, the libraries in mbsystem-5.1.3/lib, and the manual pages in mbsystem-5.1.3/man/man1.

Naturally, in order for users to use the MB-System utilities, the directory containing the executables must be included in their path. Altering the user path variable is generally accomplished by editing the initialization files hidden in the user's home directory. Which files need to be edited depends on which command line shell is being used. If the user works with csh, then the .cshrc and .login files need to be changed. If the shell is bash, then the .bashrc and .profile files must be altered. See the manual pages for the relevant shell program to determine how to set the user environment. The executable perl must also be available in the user's path for most of the macros to work.

Most users will also wish to specify which program they generally use to view Postscript plots on their screen. This parameter is set with the mbdefaults program (see the mbdefaults manual page for details). Popular open source options for Postscript display include ghostview and gv. The postscript plots can also be imported into proprietary tools like Adobe Illustrator, Adobe Acrobat, or Preview on MacOs X. On old Unix machines, pageview worked well on Sun workstations running Solaris, and xpsview on on Silicon Graphics machines running Irix.

Last Updated: $Id: mbsystem_how_to_get.html 2185 2014-05-11 06:34:36Z caress $

Back to MB-System Home Page...