MatTomo Users Guide

Rick Gaudette

Boulder Laboratory for 3D Electron Microscopy of Cells

University of Colorado, Boulder, CO, 80309



Introduction

MatTomo is a set of MATLAB objects that provide for the manipulation of IMOD model and MRC image files. Using the MatTomo classes the contents of both types of files can be read into MATLAB, their data can be examined, both graphically and textually, changed, deleted and appended. The meta data (header) can also be viewed and modified.


IMOD model files

IMOD model files consist of a hierarchy of data structures. At the highest level is the IMOD model which contains which contains a collection of meta data in the header and is followed by an arbitrary number of IMOD Object data structures. Not to be confused with the generic term “object” from object oriented programming, an IMOD Object is a specific data structure that stores information about 3D objects from the 3dmod program. Like the IMOD model structure, the IMOD Object structure contains a header followed by an arbitrary number of IMOD Contour and possibly IMOD Mesh objects that define the contours and meshes associated with the object. There are also several additional optional data structures that can be associated with the above structures by following them in the file. Most of these optional structures are currently ignored by the MatTomo methods.

The MatTomo toolbox manages the data structures in an IMOD model file through a set of classes with the obvious names of ImodModel, ImodObject, ImodContour and ImodMesh. An ImodObject contains a collection of ImodContours and possibly ImodMesh objects, and an ImodModel contains collection of ImodObject objects, thus enforcing the hierarchy described above. Many of the data manipulation methods for the lower level objects are accessible through the ImodModel object via pass through methods, although there are some instances where a lower level object must be extracted, modified, and reinserted.

Creating an IMOD model

An ImodModel first needs be instantiated before we can operate on, or store any data in the object. This can be accomplished with

imodModel = ImodModel;

which will create a default ImodModel object containing no ImodObjects.

Adding points to a model

The empty ImodModel above is not very useful without any data, to add an ImodObject containing an ImodContour to the model we could execute the following

points = [
-1 2 5 2 5;
-1 4 2 5 6;
-1 3 5 2 7 ];
imodContour = ImodContour(points);
imodObject = setContour(ImodObject, imodContour, 1);
imodModel = setObject(imodModel, imodObject, 1);

Appending a new object to a model

Since appending an ImodObject to an existing ImodModel and appending an ImodContour to an existing ImodObject are common operations, methods are available in ImodModel and ImodObject that automatically insert the supplied object at the end of the object list. We could have accomplished the same result as above with the commands

imodModel2 = ImodModel;
points = [
-1 2 5 2 5;
-1 4 2 5 6;
-1 3 5 2 7 ];
imodObject = appendContour(ImodObject, ImodContour(points));
imodModel2 = appendObject(imodModel2, imodObject);

Getting points from a model

A specific contour, or set of points, can be extracted from a model with the get* functions. If we wanted to extract the points we just inserted in the above example we could use

idxObject = 1; idxContour = 1;
objectOut = getObject(imodModel2, idxObject);
contourOut = getContour(objectOut, idxContour);
pointsOut = getPoints(contourOut);

Again, because this is such a common operation a method at the ImodModel level is available to accomplish the same result,

pointsOut = getPoints(imodModel2, idxObject, idxContour);

Changing the points of specific object and contour

To modify the data in a model, there are number of get* and set* methods available. Assume, for example, we want to multiply the contour we were working with above by 2. The could be accomplish by the following commands

idxObject = 1; idxContour = 1;
objectOut = getObject(imodModel2, idxObject);
contourOut = getContour(objectOut, idxContour);
pointsOut = getPoints(contourOut);
pointsIn = 2 * pointsOut;
contourIn = setPoints(contourOut, pointsIn);
objectIn = setContour(objectOut, contourIn, idxContour);
imodModel2 = setObject(imodModel2, objectIn, idxObject);

Or, if we wanted to work directly with the ImodModel methods, we could use

pointsOut = getPoints(imodModel2, idxObject, idxContour);
pointsIn = pointsOut * 2;
imodModel2 = setPoints(modModel2, idxObject, idxContour, pointsIn);

Reading and writing IMOD models

Reading and writing IMOD model files is supported through methods in the ImodModel class. The simplest way to read in an IMOD model file is to specify the model filename as argument to the class constructor, as in

modIDA1 = ImodModel('input.mod')

which will read in the IMOD model file named 'input.mod' in the current directory. The write method will write out the ImodModel object as an IMOD model file. For example,

modOut = write(modIDA1, 'newModel.mod');

will write out the previously read in model to an new file called newModel.mod.

ImodModel utilites

There are several utility methods available in the ImodModel class. For instance, to show the header of the model file,

showHeader(modOut);

will print out the header to the command window.

Examining the points of the model textually can be accomplished using the get* commands described above. To view them graphically, the draw command is available.

draw(modOut)

will draw the complete model as a 3D point plot. Finally, the points in a specific contour can be sorted by their 2-norm distance from a specified model point. For instance, if we wanted to sort the first example starting with the last point

imodModel = sortPoints(imodModel, 1, 1, 5)

would result in

getPoints(imodModel,1 ,1)
ans =
5 5 2 2 -1
6 2 4 5 -1
7 5 3 2 -1

To view a model inside of 3dmod we need to specify the range of the model data if we are creating a new model, an existing model from 3dmod should already have this specified. If the model is based on an MRC image stack then the range of the model should match the size of the MRCImage object. To set the model to the MRCImage range ...............

MRC image files

MRC image files consist of a 3D data volume preceded by a header containing meta data about the data volume. The MRCImage object provides for loading, saving, and modifying the volume data and meta data. Some simple examples of these operations are provided below.

Loading and saving MRC image files

Assuming that a MRC image file called 'volume.mrc' exists in the current directory. To load this into a MRCImage object we can use the constructor

mrcImage = MRCImage('volume.mrc');

Since volume data in general, and MRC image files in particular, can be extremely large the MRCImage object allows the user to specify whether the volume data will be loaded into memory or accessed only when needed from the file. By supplying a zero in the last argument of the constructor we can tell the MRCImage object to load data only when it is needed, such as

mrcFile = MRCImage('volume.mrc', 0);

The default behavior is to load the whole dataset. Use the save method to save a MRCImage object to a MRC image file. For example,

mrcFile = save(mrcFile);

will write out the contents of the object to the file stored in the filename attribute,

mrcFile = save(mrcFile, 'newfile.mrc');

will save the same dataset to a new file called 'newfile.mrc'.

Accessing and changing data

The complete volume of the MRCImage can be accessed and modified through the getVolume and setVolume methods. For example,

vol = getVolume(mrcFile, [], [], []);

will return the 3D volume data array stored in mrcFile, and

mrcFile = setVolume(mrcFile, vol);

will replace the volume data in the mrcFile object. Arbitrary sub-regions of data can also be extracted or replaced using these methods, see the MATLAB help for more information. More information about the capabilites of these classes can be found in the class directories @ImodContour, @ImodObject, @ImodModel, @ImodMesh, and @MRCmage.