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.
Note that a bonafide 3-button mouse is necessary for operations within the GUIs for viewing grids and editing and navigation adjustment of survey data.
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-bin 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, 22 and 24.
Log out and log back in after installing the prerequisites so that the X11 server will load updated resources such as fonts.
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
Ubuntu 18 has a version of CMake that is too old to work with MB-System’s CMake build system. Therefore MB-System can only be built and installed on Ubuntu 18 using the old Autotools based build system. Neither the photomosaicing nor the Terrain Relative Navigation tools can be built under Ubuntu 18 because the versions of gcc and OpenCV are too old.
Ubuntu and Debian Linux distributions include multiple tools for managing software distributions. We recommend using the command line program apt to install the prerequisite software for MB-System.
Install Ubuntu 18 from an ISO image of the release (https://ubuntu.com/download/desktop).
Update the starting packages:
Install compilers and other essential software:
Install MB-System prerequisites:
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
MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Ubuntu 18.
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
Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there.
Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace this filename with the name of the current release.)
Only option for this operating system: **Autotools Build System**
At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build the entire MB-System package.
./configure
The MB-System libraries will be placed in /usr/local/lib/, but the runtime dynamic linker does not look for shared libraries in this directory by default. Users can add /usr/local/lib to the directories searched for shared libraries by adding “/usr/local/lib” to the environment variable LD_LIBRARY_PATH. This is accomplished by placing the command
in an environment file in the user’s home directory named .zprofile (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. The preferred alternative to using LD_LIBRARY_PATH is to embed the shared library location in the compiled libraries and executables by passing an rpath command to the linker by setting the LD_FLAGS environment variable available to the configure command:
LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \ ./configure
Once the makefiles have been generated configure, build and install MB-System using:
This example is relevant for both Debian 11 and 12 because the prerequisite package names are the same.
Install Debian 11 or 12 from an ISO image of the release downloaded from https://www.debian.org.Update the starting packages:
sudo apt install netcdf-bin libnetcdf-dev libgdal-dev \ gmt libgmt6 libgmt-dev libproj-dev \ libfftw3-bin libfftw3-dev libmotif-dev \ xfonts-100dpi libglu1-mesa-dev \ libopencv-dev gfortran
MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Debian 11 and 12.
Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). 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.)
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 either Debian 11 or 12 as long as the prerequisite software packages have been installed. Finally, install MB-System.
mkdir build cd build cmake .. make sudo make install
Option 2: **Autotools Build System** (not recommended)
(Note that the CMake build system, option 1 above, builds the binaries such that the runtime libraries are reliably found without any additional commands or argument.)
Once the makefiles have been generated, install MB-System:
This example is relevant for CentOs 7, and includes building the core MB-System programs plus the Terrain Relative Navigation tools, but not the photomosaicing tools (which require a more recent version of OpenCV than included in CentOs 7).
CentOs and Red Hat Linux distributions include multiple tools for managing software distributions. We recommend using the command line program yum to install the prerequisite software for MB-System.
Install CentOs 7 from an ISO image of the release downloaded from https://www.centos.org/download/
sudo yum upgrade
Install EPEL repo:
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
Only option for this operating system: Autotools Build System
At that location (for this example, /usr/local/src/MB-System-5.7.9/), execute the configure script, named configure, with the following options to build the entire MB-System package.
./configure --enable-mbtrn --enable-mbtnav
LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \ ./configure --enable-mbtrn --enable-mbtnav
Once the makefiles have been generated by configure, build and install MB-System using:
CygWin is a collection of software tools that augment Windows computers with a Unix-style environment within which one can build, install, and run Unix-y packages like MB-System.
If Cygwin has been installed on a Windows system, then one must install a number of additional prerequisite packages before building MB-System. The package installation is done using the Cygwin setup program **setyo0x86_64,exe** rather than through Linux-style package managers like **apt** or **yum**. This example installs the core command lineprograms of MB-System without any of the graphical tools. For this purpose the prerequisite packages include:
Once Cygwin and the prerequisite packages are installed, proceed as follows:
Download the MB-System source package from the repository at GitHub:https://github.com/dwcaress/MB-SystemThere 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
At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build MB-System without any graphical tools:
./configure \ --enable-mbtrn --enable-mbtnav \ --disable-dependency-tracking --disable-mbtools
Once the makefiles have been generated by configure, install MB-System:
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 Debian 12 Linux, 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 in the Github repository at:https://github.com/dwcaress/MB-System/tree/master/docker/README.mdhttps://github.com/dwcaress/MB-System/tree/master/docker/README.pdf
There currently are no packaged distributions of MB-System. We are working on establishing them again.