Handling of structural neuroimaging file formats for Julia.
Author dfsp-spirit
11 Stars
Updated Last
1 Year Ago
Started In
January 2021


Handling of structural neuroimaging file formats for Julia.


The NeuroFormats package provides an API for reading structural neuroimaging data files in Julia. The focus is on surface-based data, as produced by FreeSurfer. The aim of the package is to allow scientists to access their neuroimaging data in Julia so they can use the language's power to implement custom data analysis pipelines.

Note that some functions for reading neuroimaging data files are available from JuliaNeuroscience, e.g., NIFTI volume and GIFTI mesh support. This package does not duplicate these functionalities.


  • Read and write FreeSurfer per-vertex data in curv format (like subject/surf/lh.thickness): functions read_curv() and write_curv()
  • Read brain meshes in FreeSurfer binary mesh format (like subject/surf/lh.white): read_surf()
  • Read FreeSurfer label files (like subject/label/lh.cortex.label): read_label()
  • Read FreeSurfer brain surface parcellations (like subject/label/lh.aparc.annot): read_annot()
  • Read and write FreeSurfer MGH and MGZ brain volumes (4D voxel images, like subject/mri/brain.mgz): read_mgh() and write_mgh()
  • Read DTI track data from MRtrix3 TCK files: read_tck()
  • Read DTI track data from DiffusionToolkit TRK files: read_trk()


You can find NeuroFormats on JuliaHub, so all you need to do is:

using Pkg

from a Julia session.


The documentation is included with the package and can be browsed online at JuliaHub. It is not repeated on this website.

Use ? to access the package documentation from within Julia, e.g., get help on a function named read_curv from within Julia by typing ?read_curv. I also encourage you to have a look at the unit tests of this package, they are essentially a collection of usage examples.

Usage Examples

Example 1: Cortical thickness on a brain mesh

The following example shows how to load a FreeSurfer brain mesh with per-vertex data and visualize it in Julia using NeuroFormats and GLMakie.

Note: If you do not have GLMakie installed, install it with Pkg.add() as described for NeuroFormats above. In that case, the example below will take a while to execute the first time you run it, as the packages will need to be precompiled first. Afterwards, visualization will be almost instant.

using NeuroFormats
using GLMakie

# Uses NeuroFormats demo data, feel free to use your own FreeSurfer data.
fs_subject_dir = joinpath(tdd(), "subjects_dir/subject1/")

surf = read_surf(joinpath(fs_subject_dir, "surf/lh.white")) # The brain mesh.
curv = read_curv(joinpath(fs_subject_dir, "surf/lh.thickness")) # cortical thickness.

vertices = surf.mesh.vertices
faces = surf.mesh.faces .+ 1

scene = mesh(vertices, faces, color = curv)


Example 2: An MRI volume

This example loads a 3D MRI scan of a brain and visualizes it.

using NeuroFormats
using GLMakie

mgh = read_mgh(joinpath(tdd(), "subjects_dir/subject1/mri/brain.mgz"))
volume = dropdims(, dims = 4) # drop time dimension, we only have one frame here.

axis = range(0, stop = 1, length = size(volume, 1))
scene3d = contour(axis, axis, axis, volume, alpha = 0.1, levels = 6)


Example 3: An atlas-based brain surface parcellation

using NeuroFormats
using GLMakie

fs_subject_dir = joinpath(tdd(), "subjects_dir/subject1/")

surf = read_surf(joinpath(fs_subject_dir, "surf/lh.white"))
annot = read_annot(joinpath(fs_subject_dir, "label/lh.aparc.annot")) # from Desikan-Killiani atlas

vertices = surf.mesh.vertices
faces = surf.mesh.faces .+ 1

scene = mesh(vertices, faces, color = vertex_colors(annot))




NeuroFormats is free software published under the GPL v3, see the LICENSE file for the full license.


Please consider citing NeuroFormats if you use it for your research.

To cite package ‘NeuroFormats’ in publications use:

  Tim Schäfer (2021). NeuroFormats: Handling of structural neuroimaging file formats for Julia. Julia package version 0.2.2.

A BibTeX entry for LaTeX users is

    title = {NeuroFormats: Handling of structural neuroimaging file formats for Julia},
    author = {Tim Schäfer},
    year = {2021},
    note = {Julia package version 0.2.2},
    url = {},

Be sure to adapt the package version to the version you actually used.

Unit tests and continuous integration

Continuous integration results:

Build Status Travis CI under Linux


If you found a bug, have any question, suggestion or comment on freesurferformats, please open an issue. I will definitely answer and try to help. You can also let me know if you need support for a new file format.

Please see for instructions on how to contribute code.

The NeuroFormats package was written by Tim Schäfer. To contact me in person, please use the email address given on my website.

Used By Packages

No packages found.