Last edit: 05-08-29 Graham Wideman

FreeSurfer

To find new additions, search for "Update"

Overview: Volumes and Surfaces

This page provides some documentation for surface file formats used with the FreeSurfer suite of programs.

Loosely speaking, the FreeSurfer suite of programs deals with two main kinds of data. Volumes of voxels, as for example from an MRI scanner, provide one source of raw input. Some FreeSurfer programs deal with manipulating and viewing these volumes and also with deriving from those volumes various surfaces.

The surface data consists of lists of vertices (and their positions in space), and faces (usually triangles, sometimes quadrangles) and the vertices associated with them. A number of FreeSurfer programs are thus devoted to manipulating, viewing and analyzing these surface files. FreeSurfer can derive some per-vertex or per-face data items, and also provides ways for you to add your own per-vertex data. This kind of associated data can also be viewed and analyzed with some FreeSurfer tools.

Vertices and Patches

FreeSurfer surface data involves vertices which will be subjected to various transformations. Consequently it's necessary to be able to track each vertex through this process, and for this purpose FreeSurfer assigns each vertex an id or "vertex number". For a set of data derived from a particular original surface analysis, a particular vertex number always refers to the same vertex, though in different surfaces the (x,y,z) values for that vertex may have been transformed. It is to this vertex number that additional data items (such as curvature, thickness or functional activity) can be attached.

Patches are subsections of complete surfaces, hence containing only a subset of the vertices. Patches retain the same vertex numbering, so that a patch's vertices can be cross-referenced to the complete set. Since a patch does not contain the complete set of vertices, the numbering of vertices in a patch will be non-contiguous.

Motivatation for This Page

In my view, to work with a suite of data-manipulating programs, it's essential to have a clear mental model of the conceptual structure of that data. Since the data digested by FreeSurfer is mostly in binary form, the structure of the data is not readily amenable to inspection.

In order to obtain a clear model, this page is an effort to document the data format of the various files that FreeSurfer employs. This should reveal the structures that are at the heart of the matter.

A caution is in order however: as with any research software, exact data formats need to be changed as the software is used and new challenges addressed. The knowledge of the conceptual structure of the data may have a lengthy shelf life, but code written to these exact binary format specs may be vulnerable to changes. The program mris_convert, which will presumably be updated to work with revised formats, may permit your programs to read/write ASCII files that are less disrupted by binary format changes.

Preliminary Notes

Surface File Formats

FreeSurfer works with a number of different file formats which define a surface. Surface files consist of:

a) a list of vertices, each with a Vertex Number, which is a unique id within this surface, and (x, y, z) positions.
b) a list of faces, giving the vertices which define the face. (Faces do not have an id.)

The main variation is whether the surface file employs triangle faces (three vertices) or quadrangle faces (four vertices). mris_convert's input code seems happy with either as input, don't know if this is the case with other FreeSurfer software.

There are other minor variations in format, and in addition some FreeSurfer programs can read surfaces from an ASCII file, or from some foreign binary formats.

Updated 2003-05-14: Note that the surface files always seems to use RAS (Right, Anterior, Superior) coordinate system. See Understanding FreeSurfer Coordinates.

FreeSurfer Triangle Surface Binary Format

Updated 2004-02-24 Verified with actual code.

(From MRISread->MRISreadOverAlloc; MRISwriteTriangularSurface)

Triangle Surface File - ASCII Version

Updated 2003-05-14: Not tested, but (x y z) is probably actually (R A S).

(From mrisWriteASCII, mrisReadAsciiFile)

Quadrangle File

Updated 2003-05-14 Verified with actual code

(From MRISwrite default code)

"New" Quadrangle File

The "new" quadrangle code in mris_convert is #if'ed out, but if it was operational it would be the same as the "old" format, with the following exceptions:

(From MRISwrite default code)

Icosahedron File

Need read_icosahedron( ) to determine this for sure, but I believe this is really just the same as FreeSurfer Triangle Surface Binary Format.

Patch Format

Patch File -Binary

The vtx data item provides the Vertex Number as follows:

If the vertex is not on the border of the patch, then vtx = -(VertexNum+1)
If the vertex is part of the border, then vtx =VertexNum+1.

Ie: the magnitude of vtx is VertexNum+1, and the sign indicates on or off the border (negative means not on border). (The one is added to avoid a problem with the sign of vertex zero.)  (To-do: Check that sense of vertex.border is 1=border!)

(From MRISreadPatch and MRISwritePatch)

Patch File - ASCII

Very similar to FreeSurfer Triangle Surface ASCII format, except that the file only includes vertices and faces that are included in the patch, and thus omits the flag showing wheher the vertex/face is included in the patch.

(From MRISwritePatchASCII.)

Patch File - Geo

See Geo Triangle File

"Additional Data" File Formats

W ("Weight") Format

A W file provides values to associate with vertices. ("W" originally stood for "weight", but now is used for generic surface overlay). Since a W file includes both a VertexNum and Value for each item, it can specify value for non-contiguously-numbered vertices, possibly providing values for only a subset of a surface's vertices, and possibly not in sequential order.

(From convertTo/FromWFile.)

W File - ASCII

(From convertTo/FromWFile.)

"Curvature" (Per-Vertex Data) Files

Notes:

 In general "curvature" files are used to associate some additional value with a vertex. Although this additional value might be a curvature as calculated by FreeSurfer, it is also useful to derive or supply other data values per vertex, and curvature-format files can be used to do this also. Thus, it might be more helpful to think of these files as "additional-value-per-vertex" files.

Also, a Curvature file is semantically very similar to a W file. The difference is that a curvature file is obliged to supply a value for every vertex, while a W file can supply a value only for a subset of vertices. (Updated 2003-07-06).

"Old" Curv File

(From MRISreadCurvatureFile)

"New" Curv File

Updated 2003-05-29

(From MRISreadNewCurvatureFile, MRISwriteCurvatureFile)

Examples of this kind of file: the lh.curv and rh.curv files produced by FreeSurfer, along with thickness and area files.

Curv File - ASCII

This file format provides a list of vertices, giving vertex number, (x,y,z) position and a single additional data value per vertex. Although this additional value can represent curvature, it can also be used to mean something else entirely.

(From writeAsciiCurvFile)

Foreign Formats

VTK File

"Visualization Toolkit" format (vtk is a popular pubic domain visualization language)

(From MRISwriteVTK )

Geo Triangle File (movie.byu format)

Need MRISwriteGeo

ICO Surface Format

"Icosahedra" surface format -- same as Triangular Surface format.

Go to:   or back to FreeSurfer home