Introduction

Welcome to the API documentation for libfs, a header-only C++11 library to read and write FreeSurfer neuroimaging data.

All relevant functions are in the file include/libfs.h and only a few utility functions are class members, so the best place to start is to open the documentation for libfs.h in the Files section above.

A note on the API doc examples

The examples in the doc strings of the libfs.h functions usually only show data preparation and the function call itself. Typically you will get a working program out of them by wrapping them into something like:

#include "libfs.h"
#include <string>
#include <iostream>
#include <vector>
// maybe more includes for some examples here.
int main(int argc, char** argv) {
     // Demo code goes here
}

To see full demo programs and compilation instructions, check the examples/ directory in the GitHub repository linked below.

Logging with libfs

You can define the output produced by libfs from your application. To do so, #define one of the following debug levels in your application, before including 'libfs.h':

LIBFS_DBG_CRITICAL // print only critical errors that will raise an expection and most likely cause application to stop (unless caught).
LIBFS_DBG_ERROR // prints errors (and more severe things).
LIBFS_DBG_WARNING // the default, prints warnings (and more severe things).
LIBFS_DBG_INFO // prints info messages, like what is currently being done.
LIBFS_DBG_VERBOSE // prints info messages inside loops, may considerable slow down apps and litter stdout.
LIBFS_DBG_EXCESSIVE // prints info messages in nested loops, will considerable slow down apps and quickly litter stdout.

Things you should know about logging and controlling libfs output:

The debug levels are ordered in the list above, and defining a single one will automatically enable all levels of higher importance (e.g., defining LIBFS_DBG_WARNING also enables LIBFS_DBG_ERROR and LIBFS_DBG_CRITICAL).
If you define nothing at all, libfs defaults to LIBFS_DBG_WARNING.
If you do not want any ouput from libfs, define LIBFS_DBG_NONE. This is not recommended though, as it completely disables all output, including critical error messages. This means that your application may terminate without any message, and is only advisable if you are very sure that you catch all possible exceptions and then produce an error message for users in your application code.
Currently all debug output goes to stdout, i.e., typically to the terminal.

The libfs project website

The project page for libfs can be found at https://github.com/dfsp-spirit/libfs. It contains information on all documentation available for libfs.