|
libfs
Header-only C++11 library for accessing FreeSurfer neuroimaging data
|
#include <iostream>#include <climits>#include <stdio.h>#include <vector>#include <fstream>#include <cassert>#include <sstream>#include <stdexcept>#include <map>#include <unordered_set>#include <unordered_map>#include <cmath>#include <algorithm>#include <chrono>#include <cstdint>
Go to the source code of this file.
Classes | |
| struct | fs::Mesh |
| Models a triangular mesh, used for brain surface meshes. More... | |
| struct | fs::Curv |
| Models a FreeSurfer curv file that contains per-vertex float data. More... | |
| struct | fs::Colortable |
| The colortable from an Annot file, can be used for parcellations and integer labels. Typically each index (in all fields) describes a brain region. More... | |
| struct | fs::Annot |
| An annotation, also known as a brain surface parcellation. Assigns to each vertex a region, identified by the region_label. The region name and color for each region can be found in the Colortable. More... | |
| struct | fs::MghHeader |
| Models the header of an MGH file. More... | |
| struct | fs::MghData |
| Models the data of an MGH file. Currently these are 1D vectors, but one can compute the 4D array using the dimXlength fields of the respective MghHeader. More... | |
| struct | fs::Mgh |
| Models a whole MGH file. More... | |
| struct | fs::Array4D< T > |
| A simple 4D array datastructure, useful for representing volume data. More... | |
| struct | fs::Label |
Functions | |
| std::string | fs::util::time_tag (std::chrono::system_clock::time_point t) |
| Get current time as string, e.g. for log messages. More... | |
| void | fs::util::log (std::string const &message, std::string const loglevel="INFO") |
| Log a message, goes to stdout. More... | |
| template<typename T > | |
| std::vector< T > | fs::util::vflatten (std::vector< std::vector< T >> values) |
| Flatten 2D vector. More... | |
| bool | fs::util::starts_with (std::string const &value, std::initializer_list< std::string > prefixes) |
| Check whether a string starts with one of the given prefixes. More... | |
| bool | fs::util::file_exists (const std::string &name) |
| Check whether a file exists (can be read) at given path. More... | |
| std::string | fs::util::fullpath (std::initializer_list< std::string > path_components, std::string path_sep=std::string("/")) |
| Construct a UNIX file system path from the given path_components. More... | |
| void | fs::util::str_to_file (const std::string &filename, const std::string rep) |
| Write the given text representation (any string) to a file. More... | |
| void | fs::read_mgh_header (MghHeader *mgh_header, const std::string &filename) |
| Read the header of a FreeSurfer volume file in MGH format into the given MghHeader struct. More... | |
| void | fs::read_mgh_header (MghHeader *mgh_header, std::istream *is) |
| Read an MGH header from a stream. More... | |
| void | fs::read_mgh (Mgh *mgh, const std::string &filename) |
| Read a FreeSurfer volume file in MGH format into the given Mgh struct. More... | |
| std::vector< std::string > | fs::read_subjectsfile (const std::string &filename) |
| Read a vector of subject identifiers from a FreeSurfer subjects file. More... | |
| void | fs::read_mgh (Mgh *mgh, std::istream *is) |
| Read MGH data from a stream. More... | |
| void | fs::read_surf (Mesh *surface, const std::string &filename) |
| Read a brain mesh from a file in binary FreeSurfer 'surf' format into the given Mesh instance. More... | |
| void | fs::read_mesh (Mesh *surface, const std::string &filename) |
| Read a triangular mesh from a surf, obj, or ply file into the given Mesh instance. More... | |
| void | fs::read_curv (Curv *curv, std::istream *is, const std::string &source_filename="") |
| Read per-vertex brain morphometry data from a FreeSurfer curv stream. More... | |
| void | fs::read_curv (Curv *curv, const std::string &filename) |
| Read Curv instance from a FreeSurfer curv format file. More... | |
| void | fs::read_annot (Annot *annot, std::istream *is) |
| Read a FreeSurfer annotation or brain surface parcellation from an annot stream. More... | |
| void | fs::read_annot (Annot *annot, const std::string &filename) |
| Read a FreeSurfer annotation from a file. More... | |
| std::vector< float > | fs::read_curv_data (const std::string &filename) |
| Read per-vertex brain morphometry data from a FreeSurfer curv format file. More... | |
| std::vector< float > | fs::read_desc_data (const std::string &filename) |
| Read per-vertex brain morphometry data from a FreeSurfer curv format or MGH format file. More... | |
| void | fs::write_curv (std::ostream &os, std::vector< float > curv_data, int32_t num_faces=100000) |
| Write curv data to a stream. More... | |
| void | fs::write_curv (const std::string &filename, std::vector< float > curv_data, const int32_t num_faces=100000) |
| Write curv data to a file. More... | |
| void | fs::write_mgh (const Mgh &mgh, std::ostream &os) |
| Write MGH data to a stream. More... | |
| void | fs::write_mgh (const Mgh &mgh, const std::string &filename) |
| Write MGH data to a file. More... | |
| void | fs::write_surf (std::vector< float > vertices, std::vector< int32_t > faces, std::ostream &os) |
| Write a mesh to a stream in FreeSurfer surf format. More... | |
| void | fs::write_surf (std::vector< float > vertices, std::vector< int32_t > faces, const std::string &filename) |
| Write a mesh to a binary file in FreeSurfer surf format. More... | |
| void | fs::write_surf (const Mesh &mesh, const std::string &filename) |
| Write a mesh to a binary file in FreeSurfer surf format. More... | |
| void | fs::read_label (Label *label, std::istream *is) |
| Read a FreeSurfer ASCII label from a stream. More... | |
| void | fs::read_label (Label *label, const std::string &filename) |
| Read a FreeSurfer ASCII label from a file. More... | |
| void | fs::write_label (const Label &label, std::ostream &os) |
| Write label data to a stream. More... | |
| void | fs::write_label (const Label &label, const std::string &filename) |
| Write label data to a file. More... | |
| void | fs::write_mesh (const Mesh &mesh, const std::string &filename) |
| Write a mesh to a file in different formats. More... | |
Variables | |
| const std::string | fs::util::LOGTAG_CRITICAL = "CRITICAL" |
| Logging threshold for critical messages. | |
| const std::string | fs::util::LOGTAG_ERROR = "ERROR" |
| Logging threshold for error messages. | |
| const std::string | fs::util::LOGTAG_WARNING = "WARNING" |
| Logging threshold for warning messages. | |
| const std::string | fs::util::LOGTAG_INFO = "INFO" |
| Logging threshold for warning messages. | |
| const std::string | fs::util::LOGTAG_VERBOSE = "VERBOSE" |
| Logging threshold for warning messages. | |
| const std::string | fs::util::LOGTAG_EXCESSIVE = "EXCESSIVE" |
| Logging threshold for warning messages. | |
| const int | fs::MRI_UCHAR = 0 |
| MRI data type representing an 8 bit unsigned integer. | |
| const int | fs::MRI_INT = 1 |
| MRI data type representing a 32 bit signed integer. | |
| const int | fs::MRI_FLOAT = 3 |
| MRI data type representing a 32 bit float. | |
| const int | fs::MRI_SHORT = 4 |
| MRI data type representing a 16 bit signed integer. | |
|
inline |
Check whether a file exists (can be read) at given path.
You should not rely on this as a pre-check when considering to open a file due to race conditions, just try-catch open in that case. This is intended to check whether a certain software run succeeded, by checking whether the key expected output files exist.
| name | the filename that should be checked. Examples |
| std::string fs::util::fullpath | ( | std::initializer_list< std::string > | path_components, |
| std::string | path_sep = std::string("/") |
||
| ) |
Construct a UNIX file system path from the given path_components.
Any trailing or leading slash (path_sep) will be stripped from the individual components and replaced with a single one between two components. If the first path component started with a slash, that slash will be kept (absolute paths are left intact).
| path_components | init list of strings, the path components |
| path_sep | path separator to use, typically / on Unix-based system. |
| std::invalid_argument | on empty |
path_sep.
|
inline |
Log a message, goes to stdout.
| message | the message to be logged. |
| loglevel | the log level, one of fs::util::LOGTAG_*. |
| void fs::read_annot | ( | Annot * | annot, |
| std::istream * | is | ||
| ) |
Read a FreeSurfer annotation or brain surface parcellation from an annot stream.
A brain parcellations contains a region table and assigns to each vertex of a surface a region.
| annot | An Annot instance to be filled. |
| is | An open istream from which to read the annot data. |
| domain_error | if the file format version is not supported or the file is missing the color table. |
| void fs::read_annot | ( | Annot * | annot, |
| const std::string & | filename | ||
| ) |
Read a FreeSurfer annotation from a file.
| annot | An Annot instance that should be filled. |
| filename | Path to the label file that should be read. |
| runtime_error | if the file cannot be opened, domain_error if the file format version is not supported or the file is missing the color table. |
| void fs::read_curv | ( | Curv * | curv, |
| std::istream * | is, | ||
| const std::string & | source_filename = "" |
||
| ) |
Read per-vertex brain morphometry data from a FreeSurfer curv stream.
The curv format is a simple binary format that stores one floating point value per vertex of a related brain surface.
| curv | A Curv instance to be filled. |
| is | An open istream from which to read the curv data. |
| domain_error | if the curv file magic mismatches or the curv file header claims that the file contains more than 1 value per vertex. |
| void fs::read_curv | ( | Curv * | curv, |
| const std::string & | filename | ||
| ) |
Read Curv instance from a FreeSurfer curv format file.
The curv format is a simple binary format that stores one floating point value per vertex of a related brain surface.
| curv | A Curv instance to be filled. |
| filename | Path to a file from which to read the curv data. |
| runtime_error | if the file cannot be opened, domain_error if the curv file magic mismatches or the curv file header claims that the file contains more than 1 value per vertex. |
| std::vector<float> fs::read_curv_data | ( | const std::string & | filename | ) |
Read per-vertex brain morphometry data from a FreeSurfer curv format file.
The curv format is a simple binary format that stores one floating point value per vertex of a related brain surface.
| filename | Path to a file from which to read the curv data. |
| runtime_error | if the file cannot be opened, domain_error if the curv file magic mismatches or the curv file header claims that the file contains more than 1 value per vertex. |
| std::vector<float> fs::read_desc_data | ( | const std::string & | filename | ) |
Read per-vertex brain morphometry data from a FreeSurfer curv format or MGH format file.
| filename | Path to a file from which to read the data. If the name ends with '.mgh' or '.MGH', this function assumes it is an MGH file. Otherwise it assumes it is a curv file. If it is an MGH file, it must contain data of type MRI_FLOAT, and it must only contain data for one subject, i.e., all dimensions with the exception of the first one should have size 1. |
| runtime_error | if the file cannot be opened, domain_error if the curv file magic mismatches or the curv file header claims that the file contains more than 1 value per vertex. |
| void fs::read_label | ( | Label * | label, |
| std::istream * | is | ||
| ) |
Read a FreeSurfer ASCII label from a stream.
A label is a list of vertices (for a surface label, given by index) or voxels (for a volume label, given by the xyz coordinates) and one floating point value per vertex/voxel. Sometimes a label is only used to define a set of vertices/voxels (like a certain brain region), and the values are irrelevant (and typically left at 0.0).
| label | A Label instance that should be filled. |
| is | An open std::istream or derived class stream from which to read the data, e.g., std::ifstream or std::istringstream. |
| std::domain_error | if the label data format is incorrect |
| void fs::read_label | ( | Label * | label, |
| const std::string & | filename | ||
| ) |
Read a FreeSurfer ASCII label from a file.
A label is a list of vertices (for a surface label, given by index) or voxels (for a volume label, given by the xyz coordinates) and one floating point value per vertex/voxel. Sometimes a label is only used to define a set of vertices/voxels (like a certain brain region), and the values are irrelevant (and typically left at 0.0).
| label | A Label instance that should be filled. |
| filename | Path to the label file that should be read. |
| std::domain_error | if the label data format is incorrect, std::runtime_error if the file cannot be opened. |
| void fs::read_mesh | ( | Mesh * | surface, |
| const std::string & | filename | ||
| ) |
Read a triangular mesh from a surf, obj, or ply file into the given Mesh instance.
| surface | a Mesh instance representing a vertex-indexed tri-mesh. This will be filled. |
| filename | The path to the file from which to read the mesh. The format will be determined from the file extension as follows. File names ending with '.obj' are loaded as Wavefront OBJ files. File names ending with '.ply' are loaded as Stanford PLY files in format version 'ascii 1.0'. All other files are loaded as FreeSurfer binary surf files. |
| runtime_error | if the file cannot be opened, domain_error if the surf file magic mismatches. |
| void fs::read_mgh | ( | Mgh * | mgh, |
| const std::string & | filename | ||
| ) |
Read a FreeSurfer volume file in MGH format into the given Mgh struct.
| mgh | An Mgh instance that should be filled with the data from the filename. |
| filename | Path to the input MGH file. |
| runtime_error | if the file uses an unsupported MRI data type. |
| void fs::read_mgh | ( | Mgh * | mgh, |
| std::istream * | is | ||
| ) |
Read MGH data from a stream.
| mgh | An Mgh instance that should be filled with the data from the stream. |
| is | Pointer to an open istream from which to read the MGH data. |
| runtime_error | if the file uses an unsupported MRI data type. |
| void fs::read_mgh_header | ( | MghHeader * | mgh_header, |
| const std::string & | filename | ||
| ) |
Read the header of a FreeSurfer volume file in MGH format into the given MghHeader struct.
| mgh_header | An MghHeader instance that should be filled with the data from the file. |
| filename | Path to the file from which to read the MGH data. |
| runtime_error | if the file cannot be opened |
| void fs::read_mgh_header | ( | MghHeader * | mgh_header, |
| std::istream * | is | ||
| ) |
Read an MGH header from a stream.
| mgh_header | An MghHeader instance that should be filled with the data from the stream. |
| is | Pointer to an open istream from which to read the MGH data. |
| runtime_error | if the file uses an unsupported MRI file format version. Only version 1 is supported (the only existing version to my knowledge). |
| std::vector<std::string> fs::read_subjectsfile | ( | const std::string & | filename | ) |
Read a vector of subject identifiers from a FreeSurfer subjects file.
| filename | a text file that contains one subject identifier per line. |
| runtime_error | if the file cannot be read |
| void fs::read_surf | ( | Mesh * | surface, |
| const std::string & | filename | ||
| ) |
Read a brain mesh from a file in binary FreeSurfer 'surf' format into the given Mesh instance.
| surface | a Mesh instance representing a vertex-indexed tri-mesh. This will be filled. |
| filename | The path to the file from which to read the mesh. Must be in binary FreeSurfer surf format. An example file is surf/lh.white. |
| runtime_error | if the file cannot be opened, domain_error if the surf file magic mismatches. |
|
inline |
Check whether a string starts with one of the given prefixes.
| value | the string for which to check whether it starts with any of the prefixes |
| prefixes | the prefixes to consider |
| void fs::util::str_to_file | ( | const std::string & | filename, |
| const std::string | rep | ||
| ) |
Write the given text representation (any string) to a file.
| filename | the file to which to write, will be overwritten if exists |
| rep | the string to write to the file |
| std::runtime_error | if the file cannot be opened. |
| std::string fs::util::time_tag | ( | std::chrono::system_clock::time_point | t | ) |
Get current time as string, e.g. for log messages.
| t | the timepoint to format as a string, typically std::system_clock::now(). |
| std::vector<T> fs::util::vflatten | ( | std::vector< std::vector< T >> | values | ) |
Flatten 2D vector.
| values | the input 2D vector. |
| void fs::write_curv | ( | std::ostream & | os, |
| std::vector< float > | curv_data, | ||
| int32_t | num_faces = 100000 |
||
| ) |
Write curv data to a stream.
A curv file contains one floating point value per vertex (or a related mesh).
| os | An output stream to which to write the data. The stream must be open, and this function will not close it after writing to it. |
| curv_data | the data to write. |
| num_faces | the value for the header field num_faces. This is not needed afaik and typically ignored. |
| void fs::write_curv | ( | const std::string & | filename, |
| std::vector< float > | curv_data, | ||
| const int32_t | num_faces = 100000 |
||
| ) |
Write curv data to a file.
A curv file contains one floating point value per vertex (or a related mesh).
| filename | The path to the output file. |
| curv_data | the data to write. |
| num_faces | the value for the header field num_faces. This is not needed afaik and typically ignored. |
| std::runtime_error | if the file cannot be opened. |
| void fs::write_label | ( | const Label & | label, |
| std::ostream & | os | ||
| ) |
Write label data to a stream.
| label | The label to write. |
| os | An open output stream. |
| void fs::write_label | ( | const Label & | label, |
| const std::string & | filename | ||
| ) |
Write label data to a file.
| label | an fs::Label instance |
| filename | Path to the label file that should be written. |
| std::runtime_error | if the file cannot be opened. |
| void fs::write_mesh | ( | const Mesh & | mesh, |
| const std::string & | filename | ||
| ) |
Write a mesh to a file in different formats.
The output format will be auto-determined from the file extension.
| mesh | The fs::Mesh instance to write. |
| filename | The path to the output file. |
| std::runtime_error | if the file cannot be opened. |
| void fs::write_mgh | ( | const Mgh & | mgh, |
| std::ostream & | os | ||
| ) |
Write MGH data to a stream.
The MGH format is a binary, big-endian FreeSurfer file format for storing 4D data. Several data types are supported, and one has to check the header to see which one is contained in a file.
| mgh | An Mgh instance that should be written. |
| os | An output stream to which to write the data. The stream must be open, and this function will not close it after writing to it. |
| std::logic_error | if the mgh header and data are inconsistent, std::domain_error if the given MRI data type is unknown or unsupported. |
| void fs::write_mgh | ( | const Mgh & | mgh, |
| const std::string & | filename | ||
| ) |
Write MGH data to a file.
The MGH format is a binary, big-endian FreeSurfer file format for storing 4D data. Several data types are supported, and one has to check the header to see which one is contained in a file.
| mgh | An Mgh instance that should be written. |
| filename | Path to an output file to which to write. |
| std::runtime_error | if the file cannot be opened, std::logic_error if the mgh header and data are inconsistent, std::domain_error if the given MRI data type is unknown or unsupported. |
| void fs::write_surf | ( | std::vector< float > | vertices, |
| std::vector< int32_t > | faces, | ||
| std::ostream & | os | ||
| ) |
Write a mesh to a stream in FreeSurfer surf format.
A surf file contains a vertex index representation of a mesh, i.e., the vertices and faces vectors.
| vertices | vector of float, length 3n for n vertices. The 3D coordinates of the vertices, typically from <Mesh_instance>.vertices. |
| faces | vector of int, length 3n for n faces. The 3 vertex indices for each face, typically from <Mesh_instance>.faces. |
| os | An output stream to which to write the data. The stream must be open, and this function will not close it after writing to it. |
| std::runtime_error | if the file cannot be opened. |
| void fs::write_surf | ( | std::vector< float > | vertices, |
| std::vector< int32_t > | faces, | ||
| const std::string & | filename | ||
| ) |
Write a mesh to a binary file in FreeSurfer surf format.
A surf file contains a vertex index representation of a mesh, i.e., the vertices and faces vectors.
| vertices | vector of float, length 3n for n vertices. The 3D coordinates of the vertices, typically from <Mesh_instance>.vertices. |
| faces | vector of int, length 3n for n faces. The 3 vertex indices for each face, typically from <Mesh_instance>.faces. |
| filename | The path to the output file. |
| std::runtime_error | if the file cannot be opened. |
| void fs::write_surf | ( | const Mesh & | mesh, |
| const std::string & | filename | ||
| ) |
Write a mesh to a binary file in FreeSurfer surf format.
A surf file contains a vertex index representation of a mesh, i.e., the vertices and faces vectors.
| mesh | The Mesh instance to write. |
| filename | The path to the output file. |
| std::runtime_error | if the file cannot be opened. |
1.8.13