gw_logo_08.gif (1982 bytes)  
Last edit: 05-08-29 Graham Wideman

FreeSurfer

Documentation for mris_convert
Article created: 2003-01-13

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

Command line

Effect

mris_convert --help

Prints help info (currently not implemented)

mris_convert -u
mris_convert -?

Prints usage info (currently not implemented)

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.

Command line

From To

Notes

mris_convert infilepath.w outfilepath

Binary W ASCII W

 

mris_convert infilepath outfilepath.w

ASCII W Binary W

mris_convert copies the vertex count from input to output without checking it -- potential for producing corrupted W file.

Note the ".w" filename extensions needed to inform mris_convert to perform a "W" file conversion. No particular extensions needed on the ASCII file.
If you specify a ".w" extension on both input and output files, then mris_convert attempts the ASCII to binary conversion, which will presumably fail.

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

Parameter

Pattern File format

Description

infilepath

xxx.ASC ASCII Triangle MRISread
xxx.GEO GEO Triangle
xxx.TRI
xxx.ICO
Triangular surface
xxx (none of above)

Quad file or
Triangular surface

outfilepath

xxx.ASC ASCII Triangle

Written by MRISwriteASCII

xxx.VTK VTK file

Written by MRISwriteVTK (I don't have this).

xxx.GEO GEO Triangle

Written by MRISwriteGeo (I don't have this.)

xxx.TRI
xxx.ICO
Triangular surface

Written by MRISwriteTriangularSurface

xxx (none of above)

Quad file

Written by MRISwrite default code ("old", since "new" appears to be #if'ed out)

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.

Parameter

Pattern File format

Description

"drvorigfilepath"

See descr. Don't know

Note: this is not an actual parameter. mris_convert attempts to derive a path for an orig file as follows: mris_convert looks at whether patchfilename starts with either "lh." or "rh.", and uses that to find and load either lh.orig or rh.orig. If the patch filename does not start with lh or rh, then mris_convert loads lh.orig, which probably has a 50% chance of being as desired.

mris_convert loads the orig file using MRISread. MRISread normally can read a variety of surface formats, dependingon filename extension. However, since in this case mris_convert derives the filename and does not use one of the special  extensions, looks like this file needs to be in one of the default binary surface formats:

-o origfilepath

any orig Optionally overwrites/rolls-back the position values that would otherwise come from the patch file? mris_convert uses MRISreadVertexPositions to load this file (which I don't have, so don't know variations permissible, but presumably reads at least FreeSurfer triangle and quadrangle files).

patchfilepath

any Patch Binary

Read by MRISreadPatch

outfilepath

xxx.ASC Patch ASCII

Written by MRISwritePatchASCII.

xxx.GEO Patch GEO

Written by MRISwriteGeo (I don't currently have this).

xxx (none of above Patch Binary

Written by MRISwritePatch default code

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.)

Parameter

Pattern File format

Description

curvinfilepath

xxx.ASC Curv ASCII

Curv file in ASCII format                                                                                                                                             .

anything else Curv binary Can be either in "old" or "new" binary curv format.

infilepath

xxx.ASC ASCII Triangle MRISread
xxx.GEO GEO Triangle
xxx.TRI
xxx.ICO
Triangular surface
xxx (none of above)

Quad file or
Triangular surface

outfilepath

 

xxx.ASC Curv ASCII

Written by writeASCIICurvFile

anything else Curv binary

Written by MRISwriteCurvature

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:

Parameter

Pattern File format

Description

All input params

    Same as for Patch and normal Curv situation

outfilepath

 

xxx.ASC Curv ASCII

As for regular Curv situation, but will include only vertices which are members of the Patch. The (x,y, z) values will be those from the patch, unless overriden by the [-o origfilepath] option.

anything else Curv binary

Written by MRISwriteCurvature -- which ignores patch membership, and outputs curv data for entire surface. Ie: this produces same result as without the -p option.

Loose Ends

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


Go to:  gw_logo_08.gif (1982 bytes)  or back to FreeSurfer page