The pure c++ implementation of the MMTF API, decoder and encoder.
C++ CMake Shell PowerShell
Switch branches/tags
Nothing to show
Clone or download
gtauriello Merge pull request #12 from rcsb/encodeToMap
Added mmtf::encodeToMap to allow applications to add custom fields to the map before it's packed.
Latest commit e77033e Jul 12, 2018

The macromolecular transmission format (MMTF) is a binary encoding of biological structures.

This repository holds the C++-03 compatible API, encoding and decoding libraries. The MMTF specification can be found here.

Prerequisites for using MMTF in C++

You need the headers of the MessagePack C++ library (version 2.1.5 or newer). If you do not have them on your machine already, you can download the "include" directory from the MessagePack GitHub repository.

How to use MMTF

You only need to include the mmtf.hpp header in your code to use MMTF. For instance a minimal example to load an MMTF file looks as follows:

#include <mmtf.hpp>

int main(int argc, char** argv) {
    mmtf::StructureData data;
    mmtf::decodeFromFile(data, "test.mmtf");
    return 0;

The C++ MMTF library is header only so you do not need to compile it. If you have a source file named demo.cpp (e.g. including the code above), you can generate an executable demo.exe as follows:

g++ -I<MSGPACK_INCLUDE_PATH> -I<MMTF_INCLUDE_PATH> demo.cpp -o demo.exe

Here, <MSGPACK_INCLUDE_PATH> and <MMTF_INCLUDE_PATH> are the paths to the "include" directories of MessagePack and this library respectively.

For your more complicated projects, a CMakeLists.txt is included for you.

Examples and tests

To build the tests + examples we recommend using the following lines:

# download Catch2 testing framework, msgpack-c, and the mmtf-spec test-dataset
git submodule update --init --recursive
mkdir build
cd build
cmake -G Ninja -DBUILD_TESTS=ON -Dmmtf_build_local=ON -Dmmtf_build_examples=ON ..
chmod +x ./tests/mmtf_tests

Example codes:

  • mmtf_demo.cpp: Loads an MMTF file and checks internal consistency using mmtf::StructureData::hasConsistentData.
./examples/mmtf_demo ../mmtf_spec/test-suite/mmtf/173D.mmtf
  • traverse.cpp: Loads an MMTF file and dumps it in human-readable forms.
./examples/traverse ../mmtf_spec/test-suite/mmtf/173D.mmtf
./examples/traverse ../mmtf_spec/test-suite/mmtf/173D.mmtf json
./examples/traverse ../mmtf_spec/test-suite/mmtf/173D.mmtf print
  • print_as_pdb.cpp: Loads an MMTF file and prints it in pdb format.
./examples/print_as_pdb ../mmtf_spec/test-suite/mmtf/173D.mmtf

Code documentation

You can generate a doxygen based documentation of the library by calling doxygen in the docs folder. You will need doxygen 1.8.11 or later for that. Open docs/html/index.html to see the generated documentation.