Getting Started with Teem

This is a very brief introduction to Teem. Teem is an open-source library (LGPL with some additional permissions), written in ANSI C. Originally, it was created by Gordon Kindlmann as a public repository of his research software, but it has grown to a project with wider scope and more contributors, including myself.

Obtaining and Building the Source Code

This section assumes that you are on Linux, have some common development tools installed (among others, you will need svn and cmake) and a basic understanding of how they work. Teem is very portable and has been successfully used in other environments, but unfortunately, I’m the wrong person to help you with those.

Since tarball releases are sparse, I recommend checking out the most recent version from the subversion repository:

svn co teem

Teem is built using cmake:

cd teem
ccmake .

On the screen that pops up, press ‘c’, and set BUILD_EXPERIMENTAL_APPS, BUILD_EXPERIMENTAL_LIBS and BUILD_SHARED_LIBS to “ON”. For CMAKE_BUILD_TYPE, enter “Release” to make sure the code is compiled with optimizations turned on. You may either install into /usr/local (default) or choose a different target by changing CMAKE_INSTALL_PREFIX. When you’re done, hit ‘c’ again and press ‘g’ to exit the screen. Now, start the compilation:


To install into your chosen target directory, do

make install

Using Teem Inside Your Own Code

I’m assuming that you have a basic understanding of how to link against a C library in the build environment of your choice. The library name for linking is “teem” (e.g., use -lteem with gcc), the include files are in a “teem” subdirectory (e.g., “#include <teem/air.h>”). Depending on the installation target, you may have to specify the appropriate include and library paths in your build environment.

Some documentation exists on the Teem homepage, but once you start to do serious work, you’ll have to start consulting the additional documentation that is located in the source files. Note that our convention is to put the documentation into the .c files along with the respective function definitions. Given a function name, the .h files will tell you in which .c file you have to look.

We agree that the current state of Teem’s documentation is far from ideal and hope to switch to doxygen in order to create detached HTML-based documentation in the future. Unfortunately, free time has been the limiting factor so far. If you should encounter a problem that is not answered by the existing documentation, do not hesitate to ask on Teem’s mailing list, which also offers a public archive.

Using Teem From the Command-Line

Teem comes with a number of useful command-line tools, which are installed into the “bin/” subdirectory of your installation target. I recommend making this directory part of your path, if it isn’t already.

Teem’s “swiss army knife” is called unu. It offers a wide range of operations that can be performed on files in Teem’s raster data file format, NRRD. If you’re experienced with Unix-style command line tools, you’ll probably get used to unu quickly and may find yourself wrapping other raster-based file formats in NRRD just to be able to use it. Fortunately, that usually only involves writing a simple ASCII header file. unu also reads and writes some standard image formats, including PNG (if libpng support has been enabled at compile time).

A set of operations that are very handy when dealing with diffusion MRI data (again stored in NRRD format) is available via the command-line tool “tend”. As with unu, you can simply type “tend” to get more information about the available functionality.