IMOD - file formats
About
The IMOD electron tomography package accepts two main types of files:
- Image Files - 2D or 3D (bitmap) images which it typically wants as MRC Image file format (which typically have an extension of: ".rec", ".mrc", ".st", ".preali", but can also be other), but it can also read in TIF files.
- Model Files - A (vector) file format which contains one or more objects (layers), where each object can contain contours (series of points connected into lines) and 3D meshes which get superimposed onto any image you open. 3dmod always saved these models using binary IMOD model file format, but can also be converted to a human readable IMOD ASCII file format and a few model other formats such as "obj" and "vrml".
There are also a bunch of text files IMOD such as "piece list files", "transformation files" (.xf) and various "com scripts" which IMOD reads in and out, but these files are all very tied in with particular command line programs and process such as tilt series reconstruction or joining files in eTomo, and so you probably won't need to play with these. In the rest of this document I explain a few useful techniques to convert or alter IMOD image and model files.
MRC Image Files
Converting images to MRC files
To convert a series of images to a single 3D MRC file you should convert to a tif sequence and then use the command:
tif2mrc tif1.tif tif2.tif tif3.tif out.rec
In this command you can enter any number of tif values, and the easiest way is to just drag the list of tif files into your command line/terminal window and (if it's a good terminal) it will automatically add all those values separated by spaces.
As a second step you should always run:
alterheader
This program will prompt you to enter important information such as pixel size.
To view the result you can open your volume in 3D mod with:
3dmod -C 1 out.rec
The "-C 1" part of this you can leave out, but is useful to add in when you have a huge file (too big to fit in memory) or you just want it to open quickly by loading just one slice at a time. You can scroll up and down slices with PgUp and PgDown.
Converting a MRC file to bytes
MRC files can store each pixel as many bytes and also store image in color..... but many of the image processing algorithms only work if you convert your volume to byte. To convert a file to bytes you can run:
mrcbyte inputvol.rec outputvol.rec
Running a command like this you should first type "man mrcbyte" and you'll see many optional arguments exist, for example "-r" to reverse contrast (useful for SEM images) or "-s 0,255" to scale the min and max byte range between those two values. Using both arguments would look like this:
mrcbyte -s0,255 -r inputvol.rec outputvol.rec
IMOD Binary File Format
Within IMOD each model contain a list of Object (think of them as "layers"), objects contains Contours (think of them as "lines") and contours contain Points. Each object can also have its contours meshed at any points to generate one or more Meshes, where each mesh can contain several different Surfaces. There are three main types of objects in IMOD:
- Closed
- Is the default and also the most common type of object.
- Contour usually has all their points on the same z slice. Although in some rare cases may you draw contours in a different 2D plane or across planes.
- The contours first and last point are usually connected, making the contour "closed", but it's also possible to individually change a contour in a closed object to "open" - useful in cases where an object might be truncated by the edge of an image.
- Adjacent closed contours are connected together to form irregular surfaces. Each surface is thus typically comprised of two or more contours.
- Mesh options can let you "cap" contours automatically, or you can manually draw a one or two point contour above/below the highest/lowest contour in each "surface".
- Is typically used to represent *closed* meshes of irregular shapes.
- Open
- Each contour can have its point wind up and down different z slices.
- The first and last point are not connected.
- Is typically meshed using the "tube" option which generates a tube-like-mesh of a fixed or variable thickness around each contour.
- Is typically used to represent tube-like structure such as microtubules and even mitochondria - since you can adjust the thickness per point and is faster than drawing multiple closed object contours per mesh.
- Scattered
- Contour points are not physically connected, but just represent a list of point.
- Should usually be given a sphere size which represents a "default radius" for points.
- Each point starts with the default radius, but using the mouse-wheel can be given a different radius.
- Is typically used to approximate tube like objects, such as vesicles, and is much faster than either method above since each point represents its own sphere/surface.
IMOD model files are stored and treated as variable length arrays in the order that they appear. Points each have their x, y and z stored as floats, although all z values are typically whole numbers starting at 0 (for the first slice) because it's rare to want to draw a contour or point between slices. The IMOD model also stores important values such as offset, scale and pixel size. A particularly important value is the "z scale", which dictates how much the model is stretched in Z relative to X and Y. In addition to the objects, the IMOD model file can also store labels for each object, contour and/or point, as well as "fine grain" (Menubar > Edit > Fine Grain) information which can be used to change properties like symbols size, color and surface number for individual points.... or to insert gaps (holes) between points in a contour (useful if a closed surface object has multiple holes).
For more information on the binary file format you can access the specifications here:
* IMOD ASCII binary file format (specifications)
Converting to other model file formats
IMOD model files can be converted to the following types of 3D files:
- vrml1 - using imod2vrml - imod2vrml input.mod out.vrml
- vrml2 - using imod2vrml2 - imod2vrml2 input.mod out.wml
- obj - using imod2obj - imod2obj input.mod out.obj
- meta - using imod2meta (used by QuickDraw 3D) - imod2rib input.mod out.rib
- rib - using imod2rib (used by Pixar's Renderman Interface) - imod2rib input.mod out.rib
Converting other model file formats to IMOD
If you have generated points in some other program and want to write out an imod file, one possible program to use is:
- point2model - which can input a text file full of points in a column output: (object num) (contour num) (pointx) (pointy) (pointz) and turn that into a binary model file - point2model input_points.txt out.mod.
The following example of an "input_points.txt" text file would generate two triangle-shaped contours in object 1, and then starts a second object:
1 1 10.00 10.00 0.00 # First object and first contour starts here and is three points: 1 1 30.00 10.00 0.00 1 1 20.00 20.00 0.00 1 2 10.00 10.00 4.00 # Object 1, contour 2 (on 3rd slice). 1 2 30.00 10.00 4.00 1 2 20.00 20.00 4.00 2 1 10.00 5.00 4.00 # Object 2, contour 1. 2 1 10.00 15.00 4.00 ... etc
This is a relatively simple format to parse out, but if you want to parse out more information like model properties and radius values you should consider using the "IMOD ASCII file format".
IMOD ASCII File Format
The imod binary file format is very condense and (obviously) in binary, but there are some cases where you might want to save your IMOD model to a "text" representation. The most likely reasons for wanting this are:
- (a) you would like to see values of all your points and model properties in a single plaintext file.
- (b) you want to write your own program which can parse in or parse out IMOD model files for the purposes of file conversion or model analysis/generation outside IMOD.
Fortunately IMOD has IMOD ASCII file format version 2.0 for just these reasons. If you just want to see the values, you can get from IMOD binary file to IMOD ASCII format with the following line:
imodinfo -a my_model_file.mod my_model_file_as_text.amod
The ".amod" extensions I use here is not official - it could just as easily be called ".txt" - but that's what I like to call these files. What's nice about the IMOD ASCII file format is that you can directly open an IMOD ASCII file in 3dmod (IMOD) the same way you would a binary model file:
3dmod image_file.rec my_model_file_as_text.amod
Once loaded in 3dmod, if you hit save it ALWAYS save our as IMOD binary file - which is something to be wary of, but is a nice way that allows you not only to go from the binary format to the ASCII format, but also go from the ASCII format back to the binary format.
Another thing you should be warned about is that IMOD ASCII format, doesn't have all the advanced features such as labels and fine grain options. Version 2.0 of the ASCII format does, however, allow you to list out all your main model, object, contour, point and mesh information, including things like point size, and so 95% of the time this is all you'll care about.
A full description of the IMOD model file format is here:
* IMOD ASCII file format version 2.0 (specifications)
One thing missing from the specifications however, are some nice easy learning examples, and so I've provided a couple of these below.
Example 1: A single object with two closed triangles
In this first example I show an example of an IMOD ASCII file with just one object, and two triangle shaped closed contours in that object:
# imod ascii file version 2.0 ## TO START WE DESCRIBE THE MODEL PROPERTIES: imod 1 # The first line is "mod" and specifies that we only have 1 object. max 512 512 100 # Gives our image dimensions in each dimension: (x) (y) (z). scale 1.7 1 1 # Shows our scale along each dimension... in this case our zScale is 1.7. # # And there are a bunch of others but the above two may actually be the only ones you care about! ## THEN WE START LISTING OUR OBJECTS IN ORDER: object 0 2 0 # Object (index starting at 0) (number of contours) (number of meshes). name My_Closed_Object # The name of our object: (name). color 0 1 0 0 # The color of our object: (r) (g) (b) (alpha). # # And are a bunch more object tags, but the ones above are the most important. # AND AFTER DEFINING EACH OBJECT WE LIST EACH CONTOUR WITH ALL ITS POINTS ON SEPARATE LINES: contour 0 0 4 # Our first contour: (index) (surface) (number of points in contour) 0 1 0 # |-- Each point is (x) (y) (z) (point size) 20 1 0 # | and you'll notice this contour has 10 15 0 # | 3 points in the shape of a triangle. contour 1 0 3 # |-- Our second contour is an identical 0 1 1 # | triangle, but is on z=1 (the 2nd slice). 20 1 1 # | 10 15 1 # | # end of IMOD model # We don't really need this, but can be good to write out anyway. #------------ # EXTRA TIPS: # > Always keep the line "imod ascii file version 2.0" at the top so IMOD can recognize what type of file it is. # > The very next line that appears should be "mod". # > Never allow a line to start with spaces, or it won't load. # > If you see contours with missing/dodgy points try removing line comments at the end of lines.
Notice that the # symbols specify a comment, and most of these I've typed myself to help you better understand the file, with the exception of the first line: "# imod ascii file version 2.0" which comes as standard and you should always include. The other lines comments you should probably remove - as well as any spaces which MediaWiki may put at the start of lines... unneeded spaces and mid line # symbols can affect the loading of the file in IMOD.
Example 2: A closed object, open object and scattered point object
This next example elaborates on the last, except that there are three objects. The first objects is a closed object (the most common, where each contour lives only on one slice) with two squares on different slices, the next object is a open object (where contour points span multiple slices and the first and last point of the contour don't connect) and a scattered point object (where contour points are not connected and each point may represents a separate sphere).
# imod ascii file version 2.0 ## TO START WE DESCRIBE THE MODEL PROPERTIES: imod 3 # The first line is imod and specifies: (number of objects). max 512 512 100 # Gives our image dimensions in each dimension: (x) (y) (z). scale 1.7 1 1 # Shows our scale along each dimension... in this case our zScale is 1.7. pixsize 5.5 # |-- Gives our pixel size and units units nm # | (1 pixel = 5.5 nm). # And are a bunch of others (eg: offsets, drawmode, refcurscale, refcurtrans, refcurrot) # but we can usually leave most of these as default by omitting them (if we want). ## THEN WE START LISTING OUR OBJECTS, CONTOURS AND POINTS IN ORDER: object 0 2 0 # Object (index starting at 0) (number of contours) (number of meshes). name My_Closed_Object # The name of our object: (name). color 0 1 0 0 # The color of our object: (r) (g) (b) (alpha). # And are a bunch more object tags, but the ones above are the most important. contour 0 0 4 # Our first contour: (index) (surface) (number of points in contour). 10 5 0 # |-- Each point is: (x) (y) (z) [point size] 10 15 0 # | and you'll notice this contour 20 15 0 # | has 4 points in the shape of 20 5 0 # | a square on z=0 (the 1st slice). contour 1 0 4 # |-- Our second contour is an identical 10 5 4 # | square, but is on z=4 (the 5th slice). 10 15 4 # | 20 15 4 # | 20 5 4 # | ## NOW LET'S GIVE AN EXAMPLE OF AN "OPEN CONTOUR" OBJECT WITH 1 (OPEN) CONTOUR: object 1 1 0 # Note: our second object (1) has (1) contour and (0) meshes. name My_Open_Object # Name for our object. color 0 1 1 0 # This one is yellow. open # Says that this is an OPEN object (important). linewidth 2 # Let's create a thicker line (default if we omit is just 1). contour 0 0 6 # This contour has 6 points. 1.33 35.33 0 # | 14 35.33 0 # | 24.66 36 2 # |-- Notice open contours are allowed to 42 36.66 2 # | have points on multiple slices. 54 36 4 # | 56.66 43.3333 6 # | And also notice we can use up to 4 decimals for x and y. ## AND FINISH WITH AN EXAMPLE OF A "SCATTERED POINT" OBJECT WITH 3 SPHERES: object 2 2 0 # Our third object (2) has (2) contours and (0) meshes listed. name My_Scattered_Object # Another very creative name. color 1 0 1 0 # Purple. open # Scattered points also have a open flag. scattered # Says that this is a SCATTERED object (important). pointsize 5 # Scattered point objects SHOULD usually have a default object size. contour 0 0 1 # Our first contour, with just one point: 12 50 0 9.5 # Centered at position (12,50,0) and has a radius of 9.5. contour 1 0 1 # Our second contour has two points: 28 50 0 4.1 # Our 2nd point has a radius of 4.1. 48 50 0 # But this last one specifies NO radius (only x,y,z). # So would inherit the default object point size of 5.
Links
- IMOD - a list of other wiki pages I've written about IMOD
- IMOD help index - list file format pages down the bottom
- MRC Image file format - AMI Scripps page
