MBARI creates and globally scales the visionary technologies required to explore, map, and understand our changing ocean.
Resources for educators, students, and anyone aspiring to learn how science and technology brings us closer to the ocean.
Integrate MBARI data with lesson plans and workshops.
Discover deep-sea critters, including exclusive footage and info.
Dive into topics about ocean health and its fascinating features.
Explore deep-sea observations with this interactive guide.
Learn about the MLML/MBARI Research Library.
Access more educational resources from the teams at MBARI.
MBARI is a non-profit oceanographic research center advancing marine science and engineering to understand our changing ocean.
Learn about MBARI’s mission, vision, and values.
Learn about our strategic priorities for the years ahead.
Meet our staff, leadership, and board of directors.
Find job openings and postdoc and internship opportunities.
Follow MBARI on social media and stay updated.
See upcoming seminars, lectures, and public events.
Access the latest annual reports and financial information.
Explore MBARI’s rich history spanning over three decades.
Get media-specific information and assets.
Find the latest job openings and join the team.
Learn about our summer internship program.
Meet our leadership and staff.
Discover deep-sea critters of all types.
Search MBARI’s library of data.
Learn about our technologies.
MB-System is an open source software package written for Unix-like operating systems, and is distributed for free as source code for download. In order to install MB-System, prerequisites need to be installed and the source distribution must be downloaded, unpacked, compiled, linked, and installed locally. The necessary steps are specific to different operating systems, so are presented separately below, after more general advice. Lastly, see the “Additional setup” toggle for steps that may be required for modules to be found by MB-System. If you are updating an existing installation, first see the toggle “Updating an MB-System Installation”.
The source code for MB-System is available from a repository on Github:https://github.com/dwcaress/MB-System
This link will open the page for the most recent stable release of MB-System. The source code distribution can be downloaded as zip or tar.gz archives from the “Assets” section at the bottom.https://github.com/dwcaress/MB-System/releases/latest
This link will open a page listing all recent MB-System releases, with the most recent release at the top. The most recent release could be a beta or pre-release. The source code distribution can be downloaded as zip or tar.gz archives from the “Assets” section at the bottom.https://github.com/dwcaress/MB-System/releases
This link will download the current state of the master branch of the MB-System repository:https://github.com/dwcaress/MB-System/archive/refs/heads/master.zip
MB-System now includes two methods for building and installing the software, which are presented as options in the instructions. The recommended method is using the CMake package (which is not available for all operating systems). The other method is based on GNU Autotools. The CMake build system is new to MB-System with version 5.7.9, and is intended to replace the older Autotools approach for current and future operating systems. The old Autotools build system will continue to be included in MB-System distributions for the forseeable future to enable building and installation on legacy operating systems. The Autotools build system will not be maintained to enable its use on current or future operating systems, and the CMake build system will not be modified to support building on legacy systems.
The sequence of commands by which one builds and installs a package using CMake is very different from Autotools. For CMake, one creates a new directory to hold the package build (commonly named “build” by convention) in the top level of the source structure, then cd’s into that directory, and then executes cmake with the argument “..”, which provides cmake the path to the top level of the source directory. CMake then copies the source into a build tree and generates Makefiles in that tree to enable compilation, linkage, and installation, again using the program make.
The GNU Autotools build system includes a script named configure at the top of the distribution structure which, when executed, generates a set of files named “Makefile” throughout the structure that hold compilation and linkage instructions used by the program make. These compilation and linkage instructions vary depending on the operating system and which versions of prerequisite software packages are installed, and in some cases special arguments must be included in the configure command. Once configure has been successfully executed, running the program make at the top level then actually invokes the local compiler and linker to build and install MB-System. Several Autotools programs, including autoconf, automake, and libtool, are used to generate the configure script included in each distribution. This build system had been the sole means by which MB-System could be built since 2011.
MB-System depends on a number of other software packages. For some operating systems, special arguments to the configure script are required to integrate the MB-System source to prerequisite software packages.
Among the software packages that are prerequisite for MB-System are:
The sections below provide instructions for building MB-System on a few common operating systems, including MacOs, Ubuntu Linux, Debian Linux, CentOs Linux, and the CygWin environment on Windows. These instructions include the installation of the prerequisite software packages using a package manager relevant to each OS and the special arguments needed for the cmake command or the configure script.
The use of MacPorts to install the MB-System prerequisite packages is recommended on Apple Mac computers, particularly because this approach enables cleanly building with a complete X11 + Motif + OpenGL infrastructure separate from the libraries and header files associated with the XQuartz package. One usually still installs XQuartz and uses it as the X11 display server, but confining the MB-System compilation and linking to headers and libraries within the MacPorts structure avoids several issues. At present, we are not able to successfully run the MB-System graphical utilities when the prerequisite packages have been installed using the Fink or Homebrew package managers.
To state it again succinctly, if you want to build and install MB-System in MacOs, use MacPorts, and **do not** use Fink or HomeBrew.
This example is relevant for MacOS 10.13 High Sierra to the current MacOS 13 Ventura on both Intel and ARM (Apple Silicon) architecture computers.
From the Apple App Store, install Xcode developer tools, which includes the LLVM compiler suite.
Install the XQuartz X11 server from https://www.xquartz.org. XQuartz 2.8.5 or later is required for all MB-System installations.
Install MacPorts using the appropriate downloadable installer package from:https://www.macports.org/install.php
After MacPorts installation, first make sure the default port packages are current by running selfupdate and then install the MB-System prerequisites.
sudo port -v selfupdate sudo port install gmt6 fftw-3 mesa libGLU openmotif xorg opencv4 pkgconfig
Also make sure that a current version of Python3 is available. First list the available Python3 versions, install the most recent, and then set port to link that version to python3:
port select --list python
Versions of Python available through MacPorts (November 6, 2023):
The most recent version is python312, so install it:
sudo port install python312 sudo port select --set python python312 sudo port select --set python3 python312
Also install the most recent Python imaging library Pillow:
sudo port install py312-Pillow
Download the MB-System source package from the repository at GitHub:https://github.com/dwcaress/MB-System
There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases
We recommend using Chrome for the download rather than Safari, because Chrome does not prematurely unpack the tarball.
Copy the MB-System distribution tarball to /usr/local/src (or somewhere else, if you prefer – this is our convention for consistency when managing many installations) and unpack it there. If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. Replace the filename with the name of the current release.
mv MB-System-5.8.0.tar.gz /usr/local/src cd /usr/local/src tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure.
cd MB-System-5.8.0
Option 1: **CMake Build System** (recommended)
At that location (/usr/local/src/MB-System-5.8.0/), create a working directory named “build”, cd into “build”, and then execute cmake at the location /usr/local/src/MB-System-5.8.0/build/. The cmake command should successfully enable building the entire current MB-System (5.7.9 or later) on any Mac computer with the prerequisites installed using MacPorts (this has been tested with computers running Monterey through Ventura.) Finally, make and install MB-System.
mkdir build cd build cmake ..
sudo make sudo make install
Option 2: **Autotools Build System** (not recommended).
At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script named **configure**, with the options necessary for your context. The XCode compiler tools do not look for header files or libraries in the locations used by MacPorts, and so it is necessary to specify these locations for several of the prerequisite packages. This command should successfully enable building the current core MB-System (5.7.9 or later) on any Mac computer with the prerequisites installed through MacPorts. This has been tested with computers running Ventura and Monterey.
./configure \ --prefix=/usr/local \ --disable-static \ --enable-shared \ --enable-hardening \ --enable-test \ --with-proj-lib=/opt/local/lib/proj9/lib \ --with-proj-include=/opt/local/lib/proj9/include \ --with-gmt-config=/opt/local/lib/gmt6/bin \ --with-fftw-lib=/opt/local/lib \ --with-fftw-include=/opt/local/include \ --with-x11-lib=/opt/local/lib \ --with-x11-include=/opt/local/include \ --with-motif-lib=/opt/local/lib \ --with-motif-include=/opt/local/include \ --with-opengl-include=/opt/local/include \ --with-opengl-lib=/opt/local/lib \ --with-otps-dir=/usr/local/src/otps
Further for Option 2: The MB-System codebase includes some components that are optional when using the Autotools build system, such as OpenCV based photomosaicing (enabled with –enable-opencv) and a realtime Terrain Relative Navigation infrastructure and toolset (–enable-mtrn and –enable-mbtnav). This configure command should enable building the entire MB-System package, including these optional tools:
./configure \ --prefix=/usr/local \ --disable-static \ --enable-shared \ --enable-hardening \ --enable-test \ --with-proj-lib=/opt/local/lib/proj9/lib \ --with-proj-include=/opt/local/lib/proj9/include \ --with-gmt-config=/opt/local/lib/gmt6/bin \ --with-fftw-lib=/opt/local/lib \ --with-fftw-include=/opt/local/include \ --with-x11-lib=/opt/local/lib \ --with-x11-include=/opt/local/include \ --with-motif-lib=/opt/local/lib \ --with-motif-include=/opt/local/include \ --with-opengl-include=/opt/local/include \ --with-opengl-lib=/opt/local/lib \ --enable-mbtrn \ --enable-mbtnav \ --enable-opencv \ --with-opencv-include=/opt/local/include/opencv4 \ --with-opencv-lib=/opt/local/lib/opencv4 \ --with-otps-dir=/usr/local/src/otps
Finally, make and install MB-System:
sudo apt upgrade
sudo apt install build-essential
sudo apt install libtirpc-dev \ netcdf-bin libnetcdf-dev libgdal-dev \ gmt libgmt6 libgmt-dev libproj-dev \ libfftw3-3 libfftw3-dev libmotif-dev \ xfonts-100dpi libglu1-mesa-dev \ libopencv-dev cmake gfortran
MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Ubuntu 20 and 22.
mv MB-System-5.8.0-tar.gz /usr/local/src cd /usr/local/src tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure:
make sudo make install
./configure \ --enable-mbtrn --enable-mbtnav --enable-opencv \ --with-opencv-include=/usr/include/opencv4 \ --with-opencv-lib=/lib/x86_64-linux-gnu
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \ ./configure \ --enable-mbtrn --enable-mbtnav --enable-opencv \ --with-opencv-include=/usr/include/opencv4 \ --with-opencv-lib=/lib/x86_64-linux-gnu
sudo apt install gmt libgmt5 libgmt-dev gmt-common \ proj-bin proj-data libproj-dev libgdal-dev \ libfftw3-3 libfftw3-dev libmotif-dev \ xfonts-100dpi libglu1-mesa-dev gfortran
sudo apt install netcdf-bin libnetcdf-dev libgdal-dev \ gmt libgmt6 libgmt-dev libproj-dev \ libfftw3-3 libfftw3-dev libmotif-dev \ xfonts-100dpi libglu1-mesa-dev \ libopencv-dev gfortran
mkdir build cd build cmake .. make sudo make install
sudo yum upgrade
sudo yum install epel-release
sudo yum install openmotif openmotif-devel \ fftw fftw-devel netcdf netcdf-devel \ proj proj-devel gdal-devel gmt gmt-devel gv \ mesa-libGL mesa-libGL-devel \ mesa-libGLU mesa-libGLU-devel
./configure --enable-mbtrn --enable-mbtnav
LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \ ./configure --enable-mbtrn --enable-mbtnav
./configure \ --enable-mbtrn --enable-mbtnav \ --disable-dependency-tracking --disable-mbtools
1. PATH environment variable
Unless one specified otherwise, the MB-System executable programs are installed in the directory /usr/local/bin. For MB-System programs to execute from a command line, the /usr/local/bin directory must be included in a user’s \$PATH environment variable. This is typically accomplished by adding a statement like
export PATH=/usr/local/bin:$PATH
in an environment file in the user’s home directory. These are often named .zshenv (if using the zsh shell), or .profile (if using the bash shell); other user environment files can be used, such as .zshrc for zsh or .bashrc for bash.
2. Enable MB-System GMT Modules (gmt.conf)
A key prerequisite for MB-System is the software package Generic Mapping Tools, or GMT. The programs mbcontour, mbswath, mbgrdtiff, and mbgrd2obj are actually GMT plug-in modules invoked as commands of the program gmt:
gmt mbcontour (…various arguments…) gmt mbswath (…various arguments…) gmt mbgrdtiff (…various arguments…) gmt mbgrd2obj (…various arguments…)
These modules are contained in a dynamically loaded or shared library that is installed into /usr/local/lib. This library is named mbsystem.so on Linux computers and either mbsystem.dylib (when installed using CMake) or mbsystem.so (when installed using Autotools) on MacOS. For GMT to successfully execute these MB-System modules, the location of this library must be known to GMT. GMT looks for the modules using an internal variable GMT_CUSTOM_LIBS loaded from a configuration file named gmt.conf. One usually enables use of the MB-System GMT modules by creating (or altering) a gmt.conf file in the user’s home directory using the gmtset module of GMT:
gmt gmtset GMT_CUSTOM_LIBS /usr/local/lib/mbsystem.so
or
gmt gmtset GMT_CUSTOM_LIBS /usr/local/lib/mbsystem.dylib
as appropriate.
Some users modify additional GMT parameters using the gmt.conf file, for example, changing the COLOR_NAN parameter to be white so transparency can be set to 255,255,255 easily in a GIS. A description of all of the gmt.conf parameters is at:https://docs.generic-mapping-tools.org/dev/gmt.conf.html.To see what GMT parameter settings are being used, type:
gmt defaults
A complexity not mentioned in the gmt.conf manual page is that GMT looks for gmt.conf first in the current working directory, then if not found, looks for it in the users home directory, and if still not found, uses the system defaults. A number of programs and plotting scripts using GMT create a gmt.conf file in the local directory, alter some of the settings in that file, use it, and then delete it before exiting. If one of these programs crashes or is interrupted before the temporary gmt.conf file is deleted, then a stray gmt.conf file is left that will become the default the next time GMT is run in that directory; we recommend deleting these extra gmt.conf files.
3. Perl ForkManager module
Several MB-System programs are written in the scripting language Perl. Three of these (mbm_multiprocess, mbm_multicopy, mbm_multidatalist) utilize a Perl library called ForkManager that enables parallel processing, and thus require that this library be installed. The management of Perl libraries is done with a tool named cpan rather than with the package managers used to install other MB-System prerequisites. Perl and cpan are available on all of the relevant operating systems. In all cases, execute:
cpan Parallel:ForkManager
MB-System installations made using these directions will install files into the following locations:
When one updates to a new MB-System version, we recommend uninstalling the previous version before installing the next. In the directory for the previous version (e.g., /usr/local/src/MB-System5.7.9/build/ if using CMake, or /usr/local/src/MB-System5.7.9/ if using Autotools), use the following command:
sudo make uninstall sudo make clean
Then follow the installation instructions appropriate for your operating system, starting with downloading the next version from GitHub.
An updated MB-System Docker Image is generated each time that a new release is created in the MB-System Github repository. This Docker is based on CentOs 7, and can be run on MacOs, Linux, and Windows computers. Data present on the host computer’s filesystems can be processed using the MB-System programs in the Docker container.
The MB-System docker image is available at https://hub.docker.com/r/mbari/mbsystem
Documentation is available at:https://github.com/dwcaress/MB-System/tree/master/docker/userhttps://github.com/dwcaress/MB-System/blob/master/docker/user/README-win11.md
There currently are no packaged distributions of MB-System. We are working on establishing them again.