IMOD - segmenting datasets
Contents
About
On this page I've written a "quickstart guide" to segmenting 3D datasets in 3dmod. 3dmod is a GUI application which comes with the IMOD software package for tomography, and is used to view and segment (i.e. delimit compartments by tracing) large 3D images (i.e "datasets"). 3dmod can also help in tracking fiducials, but the purpose of this page is to help you quickly get started with tracing data in IMOD. If you wish to read about all the functionality of 3dmod I suggest you go to the IMOD website at: http://bio3d.colorado.edu/imod/doc/3dmodguide.html . The purpose of this page is to provide a practical guide to get you up and running as soon as possible, and helping point you in the direction of the fastest tools to get the job done. This page assumes you already have IMOD installed (see IMOD - tutorial) and you also have a 3D image file - probably with an .rec or .mrc or .st extension - which you (or probably your boss) wants to segment into a 3D model.
Opening your dataset in 3Dmod
For arguments sake, lets say you have a dataset called "mydataset.rec" in the directory "/Users/username/data1/". To open your dataset the easiest way is to open a command line window... if you are using a Mac use the Terminal (should be at: /Applications/Utilities/Terminal) or if using Windows open Cygwin (usually installed to C:/cygwin/ during IMOD install process). Once your terminal is open you can start 3dmod by typing
3dmod
... and here you can browse for your dataset and model file (if you already have a model file), select from the other options (such as loading only a small number of sections at a time) and hit ok.
Since you'll be opening this dataset pretty regularly, I suggest the faster way to open your dataset is to type the following:
3dmod /Users/username/data1/mydataset.rec /Users/username/mydataset/data1/mydataset.mod
The direction of the slashes depends on wether you use Windows or Mac, but in most cases you can simply drag the file into the command line and it will put in the correct thing. The command above will automatically try to open your dataset in 3dmod, but don't be suprised if you get an error message. If your dataset is several gigabytes (and most datasets these days are this huge!), it won't fit into your computer's memory, so you'll instead need to use a slightly different command.
3dmod -C 1 /Users/username/data1/mydataset.rec /Users/username/mydataset/data1/mydataset.mod
The "-C 1" argument is a good command to use, because it will only open a single section into memory on startup (the rest will load as you navigate the dataset), so it means 3dmod will open very quickly. If you find your only interested in tracing a small region of a huge dataset, an even better method is to open only that specific region in X and Y (and maybe Z too) using this command:
3dmod -x 0,1000 -y 1000,1500 -z 10 100 /Users/username/data1/mydataset.rec /Users/username/mydataset/data1/mydataset.mod
The advantage of this method is that, if you specify a small enough region (in this case it would be 1000x500x100, so about 50 MB in size) this whole region will load into memory, so although you may have to wait a while for it to load at the start... once it's finished it will be very quick to scroll though all the slices. On opening your dataset for the first time you'll want to make sure you save the model. Simply go: Menubar > File > Save Model. As good practice, you should give the model the same name as the image file, but always change the extension to .mod. In the command lines above you'll notice I'm opening the .rec file AND a .mod file, so when you go to save, it will save to the correct place, even if the file doesn't exist yet. If you just wanted to open the image without a model you simple leave out the .mod (the last argument):
cd /Users/username/data1/ 3dmod -x 0,1000 -y 1000,1500 -z 10 100 mydataset.rec
Notice in this command above I've used cd "change directory" to "move" to the correct folder, meaning that I can just type "mydataset.rec" rather than the whole file name. As a quick warning: if you have any spaces in your file name or path you it will think you are typing separate arguments. I recommend you never use spaces, but if they are then already you can get around this by surrounding your file path with double quotes.... for example on a windows machine:
3dmod "C:\Users\YourUsername\My Documents\data1\mydataset.mod"
Once you find the IMOD commands which work for you I recommend you save them all to a text file (lets say "IMOD_COMMANDS.txt"), so that you not only remember exactly what you typed and where your data is, but you can can use copy-and-paste (or drag and drop) to quickly launch 3dmod.
Drawing Contours and Adding Objects
When you first open IMOD it starts in "movie" mode, so you'll have to change it to "model" mode in the main 3D window (the little one) before you can draw contours in the big window, called the "ZaP window". Notice this main 3D window always shows you what object, contour and point you have selected, so it a good way to change between objects or contours. It also lets you adjust the contrast (draw the black and white slides), but the best thing you can do is just hit "Auto" to auto-contrast automatically.
To add a new object simply go Menubar > Edit > Object > New. Now you should give it a smart name (eg: "Nucleus) and can change things like line thickness etc. Notice there are three types of contours:
- "Closed" - Best for most complex shapes whereby draw closed polygon and each polygon exists in one slice only.
- When a "closed object" is meshed, it will connect together contours that overlap in Z; thus each surface usually spans multiple contours and can be capped at the top and bottom with a single point. Some people like to create a separate object for each surface, but this isn't necessary - I prefer to segment all of one type of compartment in a single object/layer.
- Even though the object is "closed" you can "cut open" individual closed contours to represent holes and/or the edges of a volume by going "Edit > Contour > Type" then click "Open", or "Edit > Fine Grain" and click "gap to next point" if there are multiple "holes".
- "Open" - Best for tube-like structure such as microtubules and even mitochondria (see here for instructions on making tubes of varying thickness) where you can rapidly trace through center of this tube with an "open line" that may span multiple slices.
- Open contours are great for measuring end-to-end length, and are typically meshed to produce one (tube) "surface" per contour.
- "Scattered" - For drawing one sphere per point, and each can have it's own radius via Edit > Point > Size then use the mouse wheel to adjust each point, meaning you can later calculate the average radius and/or histogram.
- Scattered points are great for calculating size histogram and average radius, and will mesh one sphere per point.
Deciding the right contour type for an object is very important, and will depend on what type of information and accuracy you need. If your surfaces are roughly spherical, scattered points are very fast because they require one click and mouse-wheel per sphere / surface. For any "tube like organelles", open contours are the fastest as they can let you approximate each "surface" with a single contour. Segmenting with closed contours is slower, but if done carefully will get you the most accurate volume and shape estimates. To help you see point and lines, you may also consider increasing the line thickness and representing points with "symbols" - something which is especially useful for open contours.
Saving and Backing Up
Autosave should save a copy of your model to "mymodel.mod~" every 5 minutes or so..... so if you do get a crash, you can usually rename this file to "mymodel_aftercrash.mod" and open it to recover your work (since the last save). However I cannot stress enough that you get into the habit of saving every 10 minutes or so... something which is very easy to do by just pressing the [s] key. Another thing I recommend you do is, after every few hours (or day) of work make a copy of this your as "mymodel_bk1_~5hrs_work.mod", then "mymodel_bk2_~10hrs_work.mod". The reason for this is (a) it helps you keep track of (approximately) how long you've been tracing and (b) means that if you somehow corrupt or overwrite your model... or accidentally deleted an entire object and then hit save (which can happen to the best of us), you still have a copy of it you can open. Hopefully you also have some system of saving backups to an external device. Just be warned that you WILL invest days (in some cases WEEKS) of work into this file, so without saving backups you run the very real possibility of losing everything.
Effective Tracing
I'm a little bit biased, but I think the best way to trace is by making sure you open the plugins "DrawingTools" and "Interpolator", which you will find under Menubar > Special > DrawingTools. These two plugins are complimentary and designed to speedup (plus add some extra excitement to) the process of manual segmentation and I've have a video of how these two complementary plugins work on a page I've dedicate to these plugins:
- http://www.andrewnoske.com/student/imod.php > then click the "Drawing Tools and Interpolator - Overview" video
Drawing Tools plugin - rapid tracing and correction of contours
Becoming proficient with these tools takes a lot of time, but I find the best drawing tool is actually "Warp" with the middle mouse button - where you can warp contours into place (and hence is perfect for correcting any poor contours from autosegmentation and/or another person). If however, you have a complex shape, you may want to switch to "Normal" drawing mode - where you draw the outer perimeter - or "Sculpt" - where you push contours in and out. In the DrawingTools plugin window you'll notice each tool has a shortcut key, so to quickly change between Normal and Warp you'd use [1] and [6] respectively. On the mouse you'll use:
- left mouse button ................ to draw point(s)
- right mouse button .............. to pan or select any point (in any contour/object)
- middle mouse..................... to move/modify point(s)
- .... and to resize the Sculpt/Warp circle you can use the scroll wheel. It's pretty much essential that you have-and-use a three button USB mouse for this stuff !
TIP: To change the configuration of mouse buttons you can go: Menubar > 3dmod > Preferences, then the "Mouse" tab and select the third assignment of mouse buttons (Right, Left, Middle)... by default the middle mouse button is used to add points, but I find that's just not intuitive so I've changed for you already.
A few shortcut keys which are very important:
- [pgup] / [pgdn] .............. to scroll up an down slices.
- TIP: If you happen to use a Macbook or any other laptop missing these keys, you can awkwardly press the function key and up/down arrow or I've added an option to the very latest IMOD version (v4.2.16) where you can go Secial > Drawing Tools > More Actions then tick "use up/down keys to scroll slices".
- [+] / [-] .............. zoom in and out
- [n].............. start new contour
- [shift+d].............. delete whole current contour
- [delete].............. use backspace to delete points
- [v].............. to open the "Model View" window.
... and if you go Menubar > Help > Shortcut keys, you'll see the full list of shortcut keys. Also under help are more extensive instructions on how to use 3dmod.
Interpolator plugin - reducing the number of contours you have to draw
Most images are hundreds of slices, so drawing EVERY organelle on EVERY slice can be a pain! Some people suggest drawing every 3rd of so slice, but as a better solution I suggest trying to master the "Interpolator" plugin. The easiest type of interpolation to master is "Linear"... with "Linear" selected, draw one contour above another contour and hit [Enter]. So long as the contours overlap enough in XY, are within "Z Bridge" slices and are in the same object, it will add a series of "interpolated contour" in between. These will be shown as dotted contours, but if you modify them and hit [Enter] it will become more permanent and refine the shape better. Think of dotted contours as contour which have not yet been "checked" and get use to hitting [enter] every time you correct or draw a new contour. "Spherical interpolation" is actually my favorite - it works great for anything roughly spherical (vesicles for example) and I show an example of this in the video listed above.
ModelView window - meshing and viewing your model in 3D
As you trace you'll probably want to see your hard work in 3D. To do this you can open the Model View window via: Menubar > Image > Model View [v] .... but I find the easier way is to just use the shortcut key [v]. Once in this mode you can use the mouse to move around and see your structures. The contours you draw are not automatically meshed, so to do this you'll need to have the ModelView selected (since this has a different menubar) and then go Menubar > Edit > Objects... [O]. The window that pops up is a convenient place to change the display of objects, including the color and transparency. You can also turn objects off, but make sure you turn them back on afterwards so you can see them in the Zap Window! Using the "Objects window" you can also turn your contours into a mesh by clicking on the "Meshing" option (bottom left) and then hit "Mesh all". If you iterate through the different objects (at the top), you can change meshing options such as "Cap" (to close the top and bottom of each surface), but that's something you can worry about at the very end after everything segmented. My big tip about the ModelView window is to close the whole window when you're not looking at it... because if you have a large model (thousands of contours) then it will slow down your machine and make it slow to trace in the Zap window.
Conclusion
This page represents the minimum information you'll need to know just to segment in IMOD. Obviously there is a lot more to IMOD than just this, so for additional information you may want to start at this page:
- http://bio3d.colorado.edu/imod/doc/3dmodguide.html "Introduction to 3dmod" on the official IMOD site
Best of luck with your segmentation.... my parting advice to you is never overdo it (don't work too many hours into the night), drink plenty of music, listen to music (if you find that helps) and most importantly: save and backup regularly!!!
Sincerely,
Andrew Noske
Links
- IMOD - contains a list of other wiki pages I've written about IMOD, including information about source code and creating plugins.
- IMOD homepage - book mark this one!
- Special plugins videos - shows a few videos I've made demonstrating use of plugins.
