Last edit: 05-08-29 Graham Wideman

FreeSurfer

Overview

See here for overview of FreeSurfer data.

The program mris_convert is concerned with performing conversions of surface data (and associated data) to and from a variety of file formats. (ie: It is not primarily concerned with analyzing or deriving new information, merely with data storage formats.) This may seem like a relatively lowly function, however an understanding of mris_convert facilitates ease of working with FreeSurfer data, and also leads to an understanding of the structure and meaning of data in the various FreeSurfer data files.

The motivation for this page is that at this time mris_convert is not concisely documented in one place, and currently lacks a "help" function. One of the FreeSurfer authors, Bruce Fischl, has kindly permitted me to derive some documentation for this program and for the file formats from mris_convert source code.

mris_convert Command Line

mris_convert is a program which you run on a unix system of some kind, from the command line. As such, it expects command line parameters in form similar to many unix programs. A concise version of the command line expected is:

mris_convert [-c curvinfilepath] [-o origfilepath] [-p] [-t] [--help] [-u or -?] infilepath outfilepath

The [square brackets] indicate, as usual, an optional parameter. The file paths refer to complete file directory and name specification, though in most cases you can first use the shell to cd to the desired directory, and then omit the directory from the filepaths you provide to mris_convert.

Also be aware that beyond the flags, mris_convert's behavior also varies according to the filenames provided, notably the filename extensions (final one-to-three characters following a period).

In general, mris_convert is case-insensitive when inspecting flags and filename extensions -- caps or lowercase are both fine.

Help

Many Different File Conversions

mris_convert has become a bit of a catch-all for conversions on surface files, and not all combinations of parameters would be useful together. Indeed, for purposes of composing the desired command line, it is useful to conceive of mris_convert as performing several relatively unrelated functions, rather than many variations of a single function. Accordingly, I will discuss the various functions separately, along with the options which apply.

"W" File Conversions

A "W" file is a binary file which essentially contains a list of vertex id numbers, and a single value to be associated with each. If either or both of the input or output filenames has a ".w" extension, then mris_convert performs a W file conversion, and nothing else, regardless of what other flags you might have specified.

Non-W Conversions

The remaining conversions operate either on an entire surface or on a patch. In addition, an input curv file (additional-value-per-vertex file) may be involved.

The main difference between surface and patch is that a surface contains a complete set of vertices and faces, whereas a patch consists of a set of vertices and faces which are a subset of some other surface.

Note that in a FreeSurfer surface, each vertex has an id number or "vertex number", and wherever a particular vertex number is seen (in data derived from a particular original surface analysis) it refers to the same vertex, though its (x,y,z) may have been transformed. (And in a patch, there will of course be many vertices missing, and hence the vertex numbers will be non-contiguous).

mris_convert always produces just a single output file. It's really this single output file you want to create that determines the flags and input file names that you need to provide. Accordingly, below I list the various output files mris_convert can produce, and how to create the appropriate command line for each.

As a further preliminary, it's worth noting that mrsi_convert always looks in the command line for at least the two trailing filenames, the last one always specifying the output file. In addition, the output filename can always (is this correct?) specify that the output format should be ASCII, by using an extension of ".asc".

Output: Surface File

Command line (no flags):

mris_convert infilepath outfilepath

Output: Patch File

Command line (-p flag):

mris_convert [-o origfilepath] -p patchfilepath outfilepath

(Note that patchfilepath is occupying the command-line position of infilepath. Unlike for the -o and -c parameters, mris_convert is not finding the patchfilepath relative to the -p flag, and indeed if you place the -p flag before the -o option, you must still position patchfilepath as the second-last parameter.)

This command has some possibly confusing variations, but the basic objective is to combine an existing patchfile with an existing orig surface file, and produce an output patch file that is some merger or reformatting of the input files. The steps are as follows:

1. mris_convert loads an orig file, whose name (rh.orig or lh.orig) is derived from patchfilepath (Note: NOT from the -o argument!).

2. mris_convert loads the patch file data and merges it with the just-loaded orig data. This flags vertices of the complete surface as members or non-members of the patch, and additionally replaces the (x, y, z) positions of the member vertices (plus updates some stats like max and min x, y z).

3. If you've provided a [-o origfilepath] (which presumably is often the same file as mris_convert read in step 1?), then mris_convert reloads the original positions of all vertices (MRISreadVertexPositions -- which I don't have). I think the intended effect here is that the merger will have absorbed only the patch membership flag from the patch file, rather than membership and position.

(This seems a round-about way to go about it, but maybe there's some special use for a [-o origfilepath] that's actually different from the origfilepath of step 1.)

4. mris_convert produces an output file, with variations described in the table below.

Output: Curv File

Command line (-c option):

mris_convert -c curvinfilepath infilepath outfilepath

This form of command is useful for the following:
a) Converting an ASCII Curv file to a binary Curv file.
b) Producing an ASCII Curv file which includes position values. (In relational terms, this amounts to a join of a Surface and a Curv file.)

Output: Curv file for Patch

It is possible to also include the patch options (-p and optional [-o origfilepath] parameters) in this scenario. This has rather different behavior depending on output file format:

Loose Ends

The -t option appears to have no impact on mris_convert.

Go to:   or back to FreeSurfer page