Go module for reading and writing structural neuroimaging file formats. Supports FreeSurfer MGH, MGZ, and related formats.
This repo contains a very early version of a Go module for reading structural neuroimaging file formats. Currently supported formats include:
- FreeSurfer brain surface format: a triangular mesh file format. Used for recon-all output files like
<subject>/surf/lh.white.- Read file format (function
ReadFsSurface) intoMeshdata structure. - Export
Meshto PLY, STL, OBJ formats. - Computation of basic
Meshproperties (vertex and face count, bounding box, average edge length, total surface area, ...).
- Read file format (function
- FreeSurfer curv format: stores per-vertex data (also known as a brain overlay), e.g., cortical thickness at each vertex of the brain mesh. Typically used for native space data for a single subject, for recon-all output files like
<subject>/surf/lh.thickness.- Read file format (function
ReadFsCurv) - Write file format (function
WriteFsCurv) - Export data to JSON format.
- Read file format (function
- FreeSurfer MGH and MGZ formats: store 3-dimensional or 4-dimensional (subject/time dimension) magnetic resonance imaging (MRI) scans of the human brain (e.g.,
<subject>/mri/brain.mgz). Can also be used to store per-vertex data, including multi-subject data on a common brain template like fsaverage (e.g., files like<subject>/surf/lh.thickness.fwhm5.fsaverage.mgh). The MGZ format is just gzip-compressed MGH format.- Read MGH format (function
ReadFsMgh) - Read MGZ format (function
ReadFsMgh), without the need to manually decompress first. The function handles both MGH and MGZ. - Full header information is available, so the image orientation can be reconstructed from the RAS information.
- Read MGH format (function
- FreeSurfer label format: these files store labels, i.e., extra information for a subset of the vertices of a mesh or the voxels of a volume. Sometimes per-vertex or per-voxel data is stored in the labels data field, but in other case the relevant information is simply whether or not a certain element (voxel, vertex) is part of the label. Used for recon-all output files like
<subject>/label/lh.cortex.label.- Read ASCII label format (function
ReadFsLabel) - See also the related utility function
VertexIsPartOfLabel
- Read ASCII label format (function
go get github.com/dfsp-spirit/neuroThe full documentation can be found on the central go documentation page at pkg.go.dev.
It includes the full API documentation and usage examples for the functions.
Demo applications that use neuro are available in the cmd/ directory:
- A command line app that reads a FreeSurfer mesh and prints some mesh information, like total surface area, average edgle length, etc: example_surface.go
- A command line app that reads per-vertex cortical thickness data from a FreeSurfer curv file and exports it to a JSON file: example_curv.go
- A command line app that reads a three-dimensional human brain scan (MRI image) from a FreeSurfer MGH file and prints some header data and the value of a voxel: example_mgh.go
- A command line app that reads a label from a FreeSurfer surface label file and optionally exports the label data to JSON format: example_label.go
Please see the Developer information if you want to compile and run the demo apps, unit tests, and similar things.
The neuro module for Go was written by Tim Schäfer.
It is free software, published under the very permissive MIT license.
Note that this library is not a part of FreeSurfer, and it is in no way endorsed by the FreeSurfer developers. Please do not contact them regarding this library, especially not for support. Open an issue in this repo instead.