3dmod(1) 3dmod(1) NAME 3dmod - Make a model from a 3-D image stack. SYNOPSIS 3dmod [options] [image filenames] [model filename] DESCRIPTION 3dmod is typically invoked with one image file, but multiple image filenames can also be given. The model filename is optional; if 3dmod is called without a model file it will create a new model. The user can load new model files using a menu selection once 3dmod is running. The model must be in the IMOD model format. If the model file does not already exist, 3dmod will create a new model under that name. The image files may also be omitted, in which case 3dmod will draw the model on top of blank images. A file containing a list of image files can be used in place of the image file names on the command line. If multiple files of different sizes are loaded, then the size of the dis- play in each dimension will be set to the maximum size of the various files, with smaller images centered in the display. If 3dmod is invoked with options but no filenames, then a dialog window will open to allow selection of an image file. If 3dmod is invoked with no options or filenames, or with the -O option, then a startup dialog will open to allow options to be set. Images can be in the MRC image format; in the TIFF format, if the appropriate TIFF library is available; in any of the formats supported by the Qt image-reading function, which include JPEG, PNG, PPM, and BMP; or in a raw format where data are packed sequentially as in MRC files. Some kinds of raw-type files will be recognized automatically and treated like MRC files. These include Hegerl's EM format, Win- kler's FFF format, PIF files produced by Bsoft, and DigitalMicrograph version 3 files. MRC files of almost any mode can be read in: byte, 16-bit integer, real, complex real, complex integer, or color (RGB). TIFF files may be byte, 16-bit integer, 32-bit integer, real, or color, where the color can be either 24-bit (RGB), 32-bit (RGBA), or 8-bit using an embedded color map. TIFF files may be organized in strips or in tiles, and files with various kinds of compression can be read, depending on the capabilities of the libraries on the system. Raw files can be read if their dimensions, data type, and header size are defined. This information can be provided with the options -r, -t, -w, -ri, and -H or through a dialog box that is brought up when a file is encountered that cannot be read by other means. By default, all gray-scale data are scaled into 8-bit bytes when they are read into program memory, but the -I option or a preference setting can be used to have data scaled into 16-bit integers instead. The use of this option is discussed further below. Color images are stored as sets of three bytes for the red, green, and blue channels. When multiple files are read in, they usually do not need to be the same mode or even the same format. The exceptions are that if any file is an RGB file, all files must be, and if any file has a colormap, all files must. Images are loaded into an image cache under certain cir- cumstances: whenever more than one file is specified, when montaged data are loaded, when files other than MRC-like are loaded, when data are loaded as integers instead of bytes with the -I option, or when you enter the -C option to limit the size of the cache. By default, the cache will be fully loaded upon program startup and the program will behave the same as with regular data loading. However, if you limit the size of the cache, images are loaded only when needed. This has various implications that are mentioned below. Starting a movie through the images will eventually load as much data as will fit into the cache. In addition, there is a dialog box to fill the cache in various ways, available through the Edit-Image-Cache Filler menu entry. Several other restrictions on image files exist. If any files other than MRC-type (MRC or raw) are loaded and the cache is used, the image volume cannot be flipped (Y and Z exchanged) unless it is fully loaded into the cache. The Pixel View window, high-resolution mode in the Graph window, and the f and F hot keys for finding pixel values will all give zeros for a non-MRC type file. If RGB files are loaded, only the Zap and Model View windows can be opened. Two windows will open upon startup: the Information Window and an image window. The Information Window is the main control window; it has a menu bar and has indicators that give information about the selected model point and the selected graphics voxel. The bottom of the infor- mation window also has a status box that shows the progress of certain operations while using 3dmod. While the image is loading, the Informa- tion Window will report the status of the image load. Selecting the Quit menu item from the File menu will cancel the image load. If the image cache feature is used, the image window will open up after the first image section is loaded; otherwise, the image window won't open until the entire image has been loaded. The ZaP Window is the default image display window used by 3dmod. It allows one to view an image at any magnification and to pan the image around inside a resizable window. Most manual model editing is done within the ZaP Window. Additional windows that may be opened via menu selection are the Slicer, XYZ, Tumbler, Graph, Pixel View, Locator, and Model View win- dows. The Slicer Window allows one to view slices through the 3-D image data. If the image cache is turned on, only images in the cache will be displayed in views that contain data from multiple Z sections. The XYZ Image Window displays slices of the 3-D image in planes per- pendicular to the X,Y and Z axis. The Tumbler Window allows one to view a small projected view of the area around the current point. The Graph Window graphs intensity along a given axis or along a given contour. The Pixel View Window shows the actual pixel values from the image file around a given point. The Locator Window shows the whole image area and a box that allows you to see and change the subarea shown in the ZaP window. The Model View Window views the model in a 3D rendering while it is being built. Multiple ZaP, Slicer, XYZ, Graph, and Tumbler windows can be opened, whereas there is only one Pixel View, Model View, and Locator window. These windows are described below. However, see the on-line help available from each window (as well as from most dialog boxes) for a comprehensive description of all of the available features. Options 3dmod will accept some Qt options (such as -style) along with the fol- lowing options: -x <min,max> -y <min,max> -z <min[,max]> The -x, -y and -z options can be used to load in a sub-area of the original image. The offsets are saved in the model so if a different area is loaded the model is automatically transformed to match the new sub area. -B <value> Bin images by the given amount in all three dimensions. For binning by 2, 3dmod averages 8 pixels to produce one display pixel. Models built on unbinned images will be displayed prop- erly on binned images and, when saved again, will display prop- erly on unbinned images again. RGB images and multiple single image files being displayed as sections may not be binned. -b <nxy[,nz]> Bin images by nxy in X and Y and by nz in Z. Omit nz for no binning in Z. -s <min,max> The -s option will scale image intensities linearly so that the min and max values will be stored as 0 and 255, respectively, in program memory (or as 0 and 65535 whe loading data as integers). Without this option, intensities are scaled between the minimum and maximum intensities in the image file. If you have multiple image files, enter 0,0 to have all files scaled the same, based on the overall minimum and maximum of all of the files. Images can be rescaled after 3dmod is running using the menu entry Edit-Image-Reload. If raw image files are being read, entering this option will set the scaling limits for these files and pre- vent them from being scanned for their minimum and maximum val- ues. -I <0 or 1> This option controls whether images are stored in program memory as 16-bit integers instead of bytes. The entered number over- rides the default loading method selected in the 3dmod Prefer- ences dialog. Enter 1 to load data as integers, or 0 to load data as bytes after you have set the default to be integers. The option will have no effect when loading color images or when all files being loaded contain bytes. When data are stored as integers, some parts of the program operate directly on the integer values (e.g., Zap, Slicer, and XYZ windows). However, the Tumbler, autocontouring, image processing, the Line Tracker, isosurfacing, and image display in the Model View window all operate on byte values. The scaling from integers to bytes is determined by the setting of the Low and High sliders in the Information window described below. See the help pages of these individual windows for more information about the implications of this scaling. -xyz This option causes the initial image window to be the XYZ window instead of the ZaP window. -S This option causes a slicer window instead of the ZaP window to be opened when the program starts. -V This option causes a model view window instead of the ZaP window to be opened when the program starts. -Z This option causes a ZaP window to be opened even if one of -xyz, -S, or -V is entered. These 4 options can all be used together to open a selected set of windows. -Y This option causes the image data to be flipped after it has been loaded. This allows one to model image planes that are normal to the Y-axis. The default is to model planes normal to the Z-axis. It is possible to flip back and forth between these two modeling orientations using the Edit Image menu item Flip. Certain cached data can not be flipped unless they are entirely loaded into memory: TIFF files, montaged images, images loaded with different binning in Z than in X and Y, and multiple sin- gle-image files. -h -help Print some quick help for 3dmod's command line options to the terminal. -O Open the startup dialog box for setting program options and selecting files. The box will be filled in with any other argu- ments included in the command line. -C <value> The -C option controls the image cache used by 3dmod. By default, 3dmod will try to load the entire image into an ordered array in memory. This option can force a given number of images to be loaded into a more flexible memory cache. Alternatively, one can limit the size of the cache in megabytes by entering a value with m or M on the end. For example, -C 200M will limit the cache to 200 megabytes. The reason for using this option is either to decrease start up time or to view large data sets that can't fit into main memory. This features works best with the ZaP Window, which always loads the image that it needs into the cache. Other image windows will only be able to access image data that are already within the cache. As a special case, entering -C 0 will set up a cache that is large enough to hold all image data but will load images only when needed. -F Fill the image cache upon program startup, before displaying any images. This option is useful if you will be using the Slicer or XYZ windows, to avoid seeing incomplete slices. This flag is not needed unless you define the size of the cache with the -C option. -p <filename> Load a file containing a piece list for the input image. This allows one to montage image sections together or to view images that are either missing sections or have sections out of order. The piece list is an ASCII text file with the following format. There are as many lines as the input image has frames (the z dimension of the image file). Each line contains three values <X> <Y> and <Z> which represent the starting location of each frame in the input image stack. Using the piece list option will also turn on the image cache with a default size equal to the total number of image z-planes that contain data. The image cache can't be turned off, but the size can be changed with the -C option. -P <nx,ny> Create an internal piece list to display images from the file in a montage of nx by ny pieces. If an external piece list file is entered with the -p option, then this option is ignored; with this option, montage information in the file header is ignored. -o <nx,ny> When creating an internal piece list with the -p option, set the overlap between pieces to nx in the X direction and ny in the Y direction. Enter negative numbers to get space (gutters) between the pieces. If this option is used together with an existing piece list (either in the image file header or entered with the -p or -M options), then the overlaps in the piece list will be adjusted to the given values. This allows one to see all the image data in a montage. -a <filename> Specify a file with angles to be shown in the Zap window tool- bar. The angles should be one per line, in degrees, as in the .rawtlt and .tlt files in tomogram processing. -r <nx,ny,nz> Set the size for raw image files to nx in X, ny in Y, and nz in Z. This entry will be applied to all raw files and will prevent the Raw Image Description dialog from being brought up for any raw files. -t <value> Specify the type of raw files using a value corresponding to an MRC mode: 0 for unsigned bytes, 1 for signed 16-bit integers, 2 for 32-bit floating point, 4 for complex (pairs of floating point numbers), 6 for unsigned 16-bit integers, or 16 for color files stored as R-G-B triplets of bytes; or, enter -1 for signed bytes. -H <value> Set the size of the header to be skipped, in bytes, for raw image files. -w Swap bytes when reading raw image files. -ri Invert images in Y when reading raw files. -f Load file as individual frames, overriding montage information in the image file header. It is possible for an image file to have piece coordinates stored in its header rather than in a separate piece list file. 3dmod will automatically load such a file as a montage, so this option is available to override this behavior and force loading as individual frames. -m This option overrides the model transformation behavior and causes the model to be loaded without any transformations. This option is useful for loading an existing model onto a data stack after it has been flipped in Y and Z or after the pixel size or origin has been changed in the image file header. -T Load multiple single-image files as files at different times (the behavior before IMOD 3.2.3). By default, such files will now become multiple sections in Z instead. -M Load Fourier transform files without mirroring the data around the origin. By default, a complex mode input file whose X dimension is odd will be loaded with replication of the data on the left side of the Y axis, to make it easier to visualize. This option can be used override that behavior if it is inappro- priate for the input file or if there is not enough memory to show the redundant data. -ci Display images in color index mode using a color table, rather than in 24-bit color mode. Color index mode only has 8 bits and works rather poorly under Qt. -cm <file> Read a specification for the false color map used in 3dmod from a file. This file can have one of two forms. One form starts with a line with 256, then has 256 lines with red, green, and blue values from 0-255. The other form starts with the number of lines to follow; then each following line has a red, green, and blue value (0-255) plus an arbitrary integer indicating the relative location of that value along the 256-color range. These location values must be in order. If the colors being specified are to be equally spaced, the location values can sim- ply be sequential values. -G Display an RGB-mode MRC file in gray-scale rather than in color. If the list of files being loaded includes a color TIFF file, all files will be displayed in color regardless of this option. -view -modv Either option will run 3dmod in model view mode, the same as using the command 3dmodv to start the program. Only 3dmodv options are allowed in this case. -E <keys> Open the windows specified by the key letters: t for Object Type, l for Object Color, h for Model Header, o for Model Off- set, s for Surf/Cont/Point, v for Contour Move, c for Contour Copy, a for Auto Contour, b for Contour Break, j for contour Join, p for Image Process, r for Image Reload, f for Image Cache Filler, n for Movies, u for Tumbler, x for Pixel View, A for Slicer Angles, G for Fine Grain, m for Locator, z for Multi-Z, e for Scale Bar, T for Line Tracker, F for Bead Fixer, and P for all externally loaded plugins. If the -V option is given, then model view dialog boxes can also be opened with key letters the same as their hot keys (m, O, C, L, B, M, V, I, U), or with D for depth cue and S for stereo. Key numbers are for other oper- ations: 1 to start in model mode, 2 to suppress query to save model when exiting. -W Output the window ID of the 3dmod Information Window and do not put 3dmod in the background automatically. -L Listen for messages on standard input instead of the clipboard, and do not put 3dmod in the background automatically. -D Run in debug mode with diagnostic output and without becoming a background process. Key letters can be added after the D (but with no intervening spaces) to turn on specific debugging out- put; e.g., u for undo, z for zap, c for control, k for key- strokes, v for model view, U for isosurface. User Interface Features A large number of dialog boxes can be opened from the menus of the Information Window and the Model View Window. Nearly all of these are tool windows that can be left open while doing other tasks in the pro- gram. These tool windows pass hot keys on to image windows, so that one can use hot keys to perform actions in an image window without hav- ing to make that window have the keyboard focus. Tool windows opened from the Information Window menu will pass keystrokes on to the most recently active image display window. Tool windows opened from the Model View Window menu (i.e., 3dmodv dialog boxes) will pass keystrokes on to the Model View Window. Preferences for some aspects of the appearance and behavior of 3dmod can be set and saved between sessions of the program, using the 3dmod Preferences dialog box available through the Edit-Options menu entry. Among other features, the font size and type and the style of the interface may be changed, the size and color of marker points can be adjusted, and custom zoom values can be defined. On Unix systems, preferences are saved to the file $HOME/.qt/3dmodrc. Only those prop- erties that the user has changed are saved to and restored from this file, while properties that have never been changed will be set to the current program defaults. The 3dmod Preferences dialog also allows the function of the three mouse buttons to be remapped in any desired way. Because of this flex- ibility, mouse functions are described here and in the help windows of 3dmod in terms of the first, second, and third buttons. By default, these correspond to the left, middle, and right buttons. By default, the sliders in 3dmod are continuously active, or hot, which means that the program will attempt to update the display as a slider is dragged. If the program can not keep up well enough, the continuous update can be stopped by pressing the Ctrl key while dragging the slider. In the Preferences dialog, a different key can be selected to control this behavior, and the behavior can be inverted so that sliders are hot only when the control key is pressed. Nearly all controls in 3dmod have tooltips that will appear when the mouse pointer is left over a control for about half a second. These tooltips can be disabled in the Preferences dialog. Snapshots can be taken of image and model view windows with hot keys. A TIFF snapshot can be taken with Ctrl-S. Snapshots in other formats such as JPEG, PNG, and SGI RGB can be taken with Shift-S or Ctrl-Shift- S. The format of these non-TIFF snapshots can be selected in the Pref- erences dialog. The Preferences dialog also has options for setting the quality of JPEG snapshots and a resolution value in dots per inch that can be stored in a TIFF or JPEG file. There is an entry in the file menu that allows you to select (and create) a directory in which snapshots will be saved. There is also an entry there to let you save TIFF snapshots from the image windows in 8-bit gray scale instead of 24-bit color. The Escape key can be used to close all windows except the Information Window, or the 3dmodv window when running 3dmodv. Information Window The Information Window is 3dmod's main control window and it is open at all times while 3dmod is running. All other windows can be opened and closed without restarting 3dmod. At the bottom of the window is a text panel with messages from the program. It is possible to edit the text there, copy and paste it elsewhere, and save it to a file. Window Control Buttons The toolbutton with the pushpin can be used to keep the Informa- tion Window on top of all other windows, including windows from other programs. The toolbutton with two up arrows can be used to raise all of the windows of the current 3dmod above windows from other programs. Undo/Redo Buttons The toolbuttons with the backward and forward arrows can be used to undo modeling actions and to redo actions that were undone, respectively. The traditional hot keys, Ctrl-Z and Ctrl-Y, can also be used for this purpose. Virtually every model change can be undone. The Model Selection Display Controls. The current Object, Contour and Point are displayed and can be changed using the arrow buttons or by typing numbers into the text boxes. Models are a collection of objects, and each object has its own display color, drawing style and list of contours. Each contour in turn contains a list of points. When drawing the current contour the beginning point is green, the end point is red and the current point is yellow. One can also move between the current Object, Contour and Point using hot keys. p/o - Go to the next/previous Object. C/c - Go to the next/previous Contour. ]/[ or >/< - Go to the next/previous Point. The Show Checkbox This checkbox controls whether the new current model point will be displayed in image windows when the object, contour, or point is changed using the spin boxes just described. By default, image windows will show the current model point, changing sec- tion if necessary. Turn off this checkbox to prevent this action. The Image Position Display Controls. The current image size and position is displayed, and the cur- rent image point can be changed using the arrow buttons or the text boxes. The arrow keys on the keyboard can also be used to move the current image point. The current Z coordinate can be moved with the Page Up and Page Down keys. Image level Sliders. The Black and White sliders can be used to adjust the contrast and brightness of the input image for all the image windows. A linear intensity ramp is made from the black level to the white level. The Function keys also can be used to control the image level, with changes having a default step size of 3. F1, F2 Controls the Black slider level. F3, F4 Controls the White slider level. F5, F6 Controls the image contrast by moving the Black and White sliders either apart or closer. F7, F8 Controls the image brightness by moving the Black and White sliders in tandem. F9 Select Color map ramp # 1. F10 Cycle through Color map ramps, 1 - 2 - 3 - 4 - 1. F11 Toggle the reversed colormap. F12 Toggle False Color. A Autocontrast (see Auto Button below.) Low and High Sliders. When data are stored in the program as 16-bit integers instead of bytes, contrast is controlled as well by two additional slid- ers, Low and High. These sliders determine an initial scaling of the stored data into the range 0 to 255, while the Black and White sliders perform their usual function of setting the scal- ing from that range to the displayed intensities. The Float Checkbox. When this box is checked, 3dmod will attempt to maintain compa- rable image contrast when going from one section to the next. It automatically adjusts the sliders when one changes sections, based on the mean and standard deviation of image intensity in the sections. The Auto Button This button is for setting contrast automatically. When you press it, the program will attempt to adjust the black and white sliders so that the displayed image has a defined mean and stan- dard deviation. The settings for the target mean and standard deviation can be changed in the 3dmod Preferences dialog box, available from the Edit-Options menu entry. Increase the target mean to make images brighter when you press the button, or reduce the standard deviation to make images have less contrast. The default behavior is for the program to do auto contrast on the first section that is displayed, as long as you are not loading a model file. In the Preferences dialog, you can make this not happen or happen always, even when loading a model. The Subarea Checkbox When this box is checked, both the float operation when going between sections and the autocontrast operation will be based only on the image area displayed in the most recently active Zap window. If there is a rubber band in the active Zap window, the area inside the rubber band is used instead. When this box is not checked, these operations are based on the entire section. The settings of this box and the Float checkbox are saved between sessions of 3dmod. The Mode Toggle Buttons. One can toggle between Movie mode and Model mode. The model can't be edited with keys and mouse buttons while in movie mode. When 3dmod first opens a new model it switches to movie mode. The Menu bar Menu items for 3dmod are selected from the menu at the top of the information window, or at the top of the screen on a Macintosh. Some menus have keyboard shortcuts (hot keys, shown in parentheses). Menu entries with ... open a dialog box, control window, or display window. File Menu New Model Create a new model. Open Model... Load a model from disk. Reload Model Reload the current model from file. Save Model Save model. (s) Save Model as... Save model with new name. Write Model as Write model as Imod, wimp, NFF or Synu files. Movie/Montage... Open window to control movie limits in X, Y, Z and time, movie snapshots, and montaged snapshots Set Snap Dir... Set a directory to put snapshots into. The same directory will be used for snapshots from the model view window. Gray Tif Snaps A checkable entry; when checked, TIFF snapshots of image windows are saved as 8-bit gray scale. Memory to TIFF... Write the whole section of a raw color image stored inside 3dmod to a TIFF file, in order to turn a montaged image bigger than the screen into a single large image. Extract File... Extract part of file selected by rubber band in top slicer window, with flipping if image is loaded flipped. Save Info Text... Write the contents of the text panel to a file. Quit Quit 3dmod. Edit Menu Model Header... Set the model's Z-Scale for viewing, its pixel size, resolution (spacing between points during contour drawing), and whether the model is drawn or not. Offsets... Offset the model data in X, Y and Z. Clean Delete all objects that contain no points (i.e., that have no contours, or only contours with no points). Object New Create a new object. Opens Object Type dialog box. Delete Delete current object, or all objects in which a contour is selected Type... Edit Object type. Color... Open requester for changing object color. Move... Move all contours from current object to another object. Combine Combine all objects in which a contour is selected into one object and delete the other objects. Info Print object information: runs imodinfo -o Clean Delete empty contours in the current object. Break by Z Break every contour in the object at every change in Z, creating as many contours as necessary so that each lies in a single Z plane. The program will ask you to confirm the operation. Flatten Flatten every contour in the object by replacing its Z values with the mean Z of the contour, rounded to the nearest integer. The program will ask you to confirm the operation. Renumber.. Move the current object to a new object number, thus changing the order of the objects. Surface New Create a new contour with a new surface number. (N) Go To... Select a different surface in the Surf/Cont/Point window. Move... Move contours in a surface to a different object or a different surface using the Contour Move window. Delete Delete the current surface, i.e. all contours with the same surface number as current contour. Contour New Create a new contour. (n) Delete Deletes the current contour. (D) Move... Move current contour to a different object or surface. Copy... Copy contours to a different object, Z-level, or time. Sort Sort contours in a closed or open contour object by their Z values and by their time values. Break... Break contour into two contours. Closed contours can have two break points. Join... Join two contours together. Closed contours will be joined at the nearest point; open contours will be joined such that the joined contour will have points up to the first selected point from the first contour and from the second selected point to the last point from the second contour. Break by Z Break a closed contour at every change in Z, creating as many contours as necessary so that each lies in a single Z plane. Fill In Z For an open contour that traverses through Z, add points by interpolation to fill in any gaps where the contour skips one or more sections. Loopback Add points to the end of a contour so that it loops back from its current end to its start along the same path. Such a contour can be used to make a complex cap over an elongated, oddly shaped contour. Invert Invert the order of points in the current contour. Info Print area and/or length of contour. Auto... Make new contours using threshold. Type... Edit contour internal data, such as surface #, time index and labels. Point Delete Delete Current point. (Delete) Size... Set size of individual points. Distance Show distance between current and last model points. Value Show current voxel value from image file. Sort by Z Sort points in a contour by Z value. Sort by dist Sort points in a contour by interpoint distance so that the closest possible points are neighbors Image Flip Exchange Y and Z dimensions of the image data. Process... Process images by filtering. Reload... Open the image scale reload requester. Fill Cache Fill the cache if there is one. Cache Filler... Open a dialog box to control cache filling and select autofilling. Fine Grain... Open window to define display properties of individual points, contours, or surfaces. Angles... Open window to save and restore angles and positions of Slicer windows. Scale bar... Open window to draw scale bars in windows. Options... Open 3dmod preferences dialog to personalize settings Image Menu ZaP Open a ZaP window. (z) Multi-Z Open a window to show array of successive slices XYZ Open an XYZ window. Slicer Open an image Slicer window. (\) Model View Open a 3dmod model view window. (v) Pixel View Open window displaying pixel values. Graph Open an image Graph window. (G) Locator Open a window to show the ZaP window subarea. Isosurface Open model view with an isosurface display display of the image data. (U) Tumbler Open a 3-D Tumbler window. Special menu This menu provides access to plugins found by 3dmod when it starts, as well as internal modules that provide special features. The latter include the Bead Fixer to assist with correcting models of fiducial markers for aligning tilt series, and the Line Tracker, which performs semi-automated modeling of linear features such as membranes. Three plugins written by Andrew Noske are now included in the IMOD distribu- tion: Bead Helper to help fixing large fiducial models; Drawing Tools with additional model tools, and Interpolator to generate contours automatically between ones that you draw. Help Menu This menu provides help for controls used in 3dmod. Topics include Man Page, Menus, and Hot Keys. ZaP Window The ZaP window allows one to zoom and pan inside of a model window that shows image sections perpendicular to the Z-axis. Multiple ZaP windows can be opened. To Zoom press the - and = keys. To pan, press the first mouse button and drag the mouse. Alternatively, use the keyboard arrow keys: the ones on the numeric keypad in movie mode, or the set of 4 arrow keys in model mode. There is a toolbar at the top of the ZaP window that controls addi- tional behavior. Press the help button on the toolbar for help. The toolbar may be detached from the window to get the maximum vertical extent of window area. The mouse buttons are assigned different functions in movie and model modes. The keyboard m key toggles between movie and model modes. Other sub modes can further change the mouse controls. First mouse button One can drag the image in the ZaP Window by moving the mouse while holding down the first mouse button. If the rubber band is on and the button is held down while the pointer is near the band, one can drag a corner or edge of the band to adjust its size. When the button is clicked in movie mode, the current image position is selected. In model mode, the nearest modeling point is selected and highlighted with a yellow circle. If no points are in proximity to the cursor, then no model point is selected and just the current image point is set. If the Ctrl key is held down in model mode, this button can be used to select multiple contours, which will be highlighted with a dis- tinct line thickness. Clicking again on a selected contour des- elects it, and clicking without the Ctrl key cancels the multi- ple selection. Second mouse button In movie mode, this button starts the movie through sections in the forward direction. In model mode, this button creates a point after the current model point (or before, if the modeling direction is set with i or the toolbar button.) Holding down the second mouse button will create additional points as the mouse moves. If the rubber band is on and the button is held down while the pointer is near the band, one can drag the whole band to a new position. Third mouse button In movie mode, this button starts the movie through sections in the reverse direction. In model mode, the selected point is modified to be at the current location. Holding down the third mouse button will cause additional points to be moved, until the end of the contour is reached. If the Ctrl key is held down, then this mouse button can be used to delete points under the cursor. Clicking the button will delete the point(s) at the current mouse position; holding the button down and moving the mouse will delete all of the points that the cursor sweeps over inthe current contour. Keyboard Controls Most controls that edit models are disabled in movie mode. Key- pad keys work regardless of whether NumLock is on. Modeling and display control keys --------------------------------- o - Go to previous object p - Go to next object ] or > - Go to previous point [ or < - Go to next point C - Go to next contour c - Go to previous contour 5 - Go to previous contour in current surface 6 - Go to next contour in current surface 7 - Go to previous surface in current object 8 - Go to next surface in current object e - Unselect current point E - Unselect current contour { or ( - Go to first point in contour } or ) - Go to last point in contour n - Create a new contour N - Create a new contour with a new surface number 0 - Create a new object Delete - Delete current model point D - Delete current contour Ctrl-D - Truncate current contour at current point Ctrl-Shift-D - Delete current surface M - Move contour to selected object k - Copy contour (when Contour Copy dialog is open) J - Join two selected contours Ctrl-B - Break contour (when Contour Break dialog is open) Ctrl-Z - Undo a change in the model Ctrl-Y - Redo a change that was undone m - Toggle model edit mode and movie mode t - Toggle model drawing on/off T - Toggle current point/contour markers on/off Ctrl-T - Toggle current object on/off g - Toggle nearby contour ghost draw mode s - Save Model File f - Print current pixel value in information window F - Find the maximum pixel within 10 pixels and report its value , - Decrease movie speed - - Decrease Zoom = - Increase Zoom 3 - Start or stop a movie through time in the forward direction 4 - Start or stop a movie through time in the backward direction # - Start or stop a movie though Z in the forward direction $ - Start or stop a movie though Z in the reverse direction S - Snapshot image in window to file with primary non-TIFF format Ctrl-S - Snapshot image in window to TIFF file Ctrl-Shift-S - Snapshot to second type of non-TIFF file Other keys active in the ZaP window only ---------------------------------------- Ctrl-A - Select all contours in current object on section or within the rubber band b - Build a contour while in auto contour mode a - Advance to and fill next section when auto contouring u - Smooth a filled area when auto contouring i - Toggle the modeling direction Z - Toggle auto section advance on and off B - Toggle rubber band on and off I - Print information about window, image size, and offsets, also bring the Information Window to the front R - Resize window to size of image or rubber band P - Activate moving current contour with first mouse button Keypad Ins - Add point(s) in model mode, like second mouse button Esc - Close ZaP window Keys to control position or move current viewing point ------------------------------------------------------ Page Up - Increase Z Page Down - Decrease Z Up Arrow - Increase Y Down Arrow - Decrease Y Right Arrow - Increase X Left Arrow - Decrease X End - Go to Z = 1 Home - Go to Z = max Insert - Go to middle Z of stack Shift-Home - Go to middle Z of stack 1,2 - Previous,Next Time Index !,@ - Go to first or last time index, or to Start or End value for Time shown in Edit-Movies dialog Keypad Arrows - Move current model point in model mode, - Pan in ZaP window in movie mode. Arrows - Pan in ZaP window in model mode Contrast control keys ----------------------------------------- A - Autocontrast F1 - Decrease Black level F2 - Increase Black level F3 - Decrease White level F4 - Increase White level F5 - Decrease contrast F6 - Increase contrast F7 - Decrease brightness F8 - Increase brightness F9 - Select color ramp #1 F10 - Cycle through color ramps 1 - 2 - 3 - 4 - 1 F11 - Invert contrast F12 - Toggle false color on/off Window control keys ----------------------------------------- \ - Open Slicer Window v - Open Model View Window G - Open Graph window z - Open ZaP window U - Open Model View with Isosurface display Ctrl-R - Raise all 3dmod windows above other windows. Slicer Window Multiple Slicer Windows can be opened. Each Slicer Window shows a dif- ferent slice through a 3-D volume. The Slicer window has two to four movable toolbars. The large toolbar contains three sliders that are used to select the orientation of the slice by setting the angles of rotation of the data volume around the X, Y and Z axes. A small dis- play next to the sliders gives a visual cue to the slice location. This toolbar also has two spin boxes, one to select the thickness of the slice being displayed, the other to select the thickness of model that will be projected onto the slice. It also has a Help button to open up on-line help. The narrow toolbar at the top of the Slicer has the following buttons, from left to right. The Up and Down arrows adjust the magnification in the slicer dis- play window. The text box shows the zoom and allows one to type in an arbitrary zoom factor. The checkerboard button toggles between nearest neighbor and slower, cubic interpolation. The Lock button will keep the Slicer from changing its current posi- tion when locked. The Centering button toggles between the default mode in which the window can be panned with the mouse, and a mode in which the current image point is kept at the center of the window (referred to as 'clas- sic' mode). The Shift Lock (Sh) button toggles a mode in which mouse buttons and keypad keys can be used to rotate the volume as if the Shift key were held down. The IM/FFT button toggles between showing an image and an FFT of the image. The Show Slice button will draw where the slice intersects the X- Y- and Z-planes in the XYZ window, and the Z-plane in the ZaP window. The Contour button sets the angles so that the current contour is flat in the slice. The Z-Scale control determines whether the model's Z-scale will be applied to stretch the volume in the Z dimension and compensate for thinning. The orientation of the slice can also be adjusted by rotating the vol- ume relative to the current axes rather than the original axes. With the Shift key held down (or with the Shift lock toolbar button on), the second mouse button will rotate the volume around an axis in the plane of the slice and perpendicular to the direction of mouse movement. The third mouse button will rotate in the plane of the slice, around the center point. One can model in the Slicer Window, using the first mouse button to select the current point, the second mouse button to insert a point after the current point, or the third button to modify the current point. The second button can be held down to insert points continu- ously. In movie mode, the first button selects the current point, and the second or third buttons together with the Ctrl key start movies forward or backward through the data, in a direction perpendicular to the slice. Hot Keys in the Slicer -/= - Decrease/Increase zoom _/+ - Decrease/Increase displayed image thickness 9/0 - Decrease/Increase displayed model thickness s - Show slice in ZaP and XYZ windows k - Toggle centering mode between new mode and classic mode S - Snapshot to file with primary non-TIFF format Ctrl-S - Snapshot to TIFF file Ctrl-Shift-S - Snapshot to second type of non-TIFF file W - Set angles so that current contour is flat in the slice x/y/z - Align current and previous model points along X, Y or Z axis X/Y/Z - Align first and last points of current contour along X, Y or Z axis Numeric Keypad (no Shift) 4/6 - (Left/Right) Decrease/Increase last adjusted angle by 0.1 2/8 - (Down/Up) Decrease/Increase last adjusted angle by 0.5 1/3 - (End/PgDn) Decrease/Increase last adjusted angle by 15.0 0 - (Insert) Set last adjusted angle to 0 Numeric Keypad (with Shift key down or Sh button on) 4/6 - (Left/Right) Rotate volume around current Y axis 2/8 - (Down/Up) Rotate volume around current Y axis 9/3 - (PgUp/PgDn) Rotate in plane of slice </> - Decrease/Increase step size for these rotations (,/. also do this if Sh is on) XYZ Window The XYZ window displays three slices: through an XY plane in the lower left, through a YZ plane in the lower right, and through an XZ plane in the upper left. The intersection of the model with these planes will be drawn. Marker lines and crosses indicate the position of the cur- rent point and of the slices within the volume. Like the ZaP window, the XYZ window can be resized, and the images can be zoomed with hot keys and panned within their view boxes with the left mouse button. Basic modeling capability is available in the XY plane. One can movie through one or more of the planes simultaneously. In addition, the marker lines have handles that can be dragged with the mouse to riffle through images in a plane. Each marker line's color matches the color of the border around the plane that is controlled by its handle. Hot Keys in the XYZ Window -/= - Decrease/Increase zoom r - Toggle between low and high resolution display modes P - Toggle on or off showing a projection of the current contour in the XZ and YZ planes, and of a current contour that is open in the XY plane S - Snapshot to file with current non-TIFF format Ctrl-S - Snapshot to TIFF file Ctrl-Shift-S - Snapshot to second type of non-TIFF file Mouse Buttons in the XYZ Window Actions in Movie Mode: Clicking the first mouse button will select the current point. In one of the three image planes, this will generally change the coordinates displayed in the other two planes. Clicking in the horizontal gutter region occupied by the X marker line will change the current X coordinate and the plane displayed in the YZ panel. Clicking in the vertical gutter region will select a new Y coordinate and XZ plane. Clicking in the upper right region will select a new Z coordinate and XY plane, as indicated by the crossed marker lines. Dragging with the first mouse button depressed will either pan the image within the window or riffle through one of the planes, depending on where the mouse is when the button is first pressed. If it is in one of the image panels, dragging will pan the image (provided it is larger than the window.) In the hori- zontal or vertical gutter regions, dragging will riffle through YZ or XZ planes, respectively. In the upper right region, drag- ging will change the XY plane; this is most effective if one grabs the handle there and moves diagonally. Clicking the second mouse button in one of the image panels will start or stop a movie in the forward direction in that panel. Clicking the third mouse button in one of the image panels will start or stop a movie in the backward direction in that panel. Actions in Model Mode: Clicking the first mouse button near a model point in the XY plane will select that point as the current model point. Click- ing anywhere else will cause the same result as in movie mode. Dragging with the first mouse button is the same as in movie mode. Clicking with the second mouse button in the XY plane will add a point to the current contour and has no effect elsewhere. Dragging with the second mouse button depressed will add a series of points to the current contour. Clicking with the right mouse button in the XY plane will move the current model point to that location. Multi-Z Window A Multi-Z Window is opened by selecting the Multi-Z item from the Image menu. The window contains an array of panels showing successive slices at the same location in the XY plane. Initially, the window will show a row of 5 slices, but you can resize it and adjust the number of rows and/or columns of slices to display. You can also select the Z inter- val between slices and control whether the model is displayed on the central slice and on the other slices. The window is a special form of Zap Window so it has much of the Zap Window functionality, including the ability to select the current image or model point with the first mouse button, but modeling is not supported. Tumbler Window The Tumbler Window is opened by selecting the Tumbler item from the Image menu. A projection of a volume around the current point will be shown in the Tumbler Window. Various toolbar controls allow you to change the size of the volume and the zoom, lock the position, select a high-resolution display, or set thresholds for truncating pixels as black or white. The image display in the model view window, accessed from the Edit-Image menu entry of that window, will give a faster and better display for most purposes, but the tumbler display will be a more accurate projection, especially in high-resolution mode. The hot keys in the tumbler window are: Keypad up and down arrow keys tumble the volume around the X axis. Keypad left and right arrow keys tumble the volume around the Y axis. Keypad PgUp and PgDn keys tumble the volume around the Z axis. -/= Decrease/Increase the zoom F5/F6 Decrease/Increase black threshold level F7/F8 Decrease/Increase white threshold level b Toggle the bounding box on or off ,/. Decrease/Increase angular increment when rotating S - Snapshot to file with current non-TIFF format Ctrl-S - Snapshot to TIFF file Graph Window This window graphs image intensity along the image X-axis, Y-axis, Z- axis or along the current contour. A histogram of image intensities can also be graphed. The type of graph can be chosen by using the option menu located in the toolbar. The [+] and [-] buttons in the toolbar adjust the zoom in the drawing area. The [LOCK] button stops the window from tracking the current point. The [RESOLUTION] button toggles between taking data from the image buffer and taking data from the file. The Width spin button lets you select the number of pixels of width across which data are averaged perpendicular to the line being graphed. Locator Window This window displays a zoomed-down view of the entire image area and a red rectangle representing the subarea displayed in the most recently active ZaP window. If the rubber band is on in that ZaP window, the rectangle shows the position of the rubber band instead. The window can eb made smaller or larger to change the zoom of the display. You can also control the area displayed in the ZaP window, and/or the posi- tion of the rubber band, in two ways. You can click with the first mouse button to select a new center. You can press and hold the second mouse button, and as you move the mouse, the ZaP center position will be moved by the corresponding amount. Pixel View Window The Pixel View window displays a 7x7 grid of buttons showing values from the image file around the current point. The pixel positions in X and Y are shown as labels on the left and bottom edges of the window. If you click a button, that coordinate will become the current point and the value shown there will move to the central button. The buttons with the highest and lowest values are shown with red and blue back- grounds, respectively. At the top of the window is a continuous read- out of the cursor position and image value at that position whenever the mouse is in a ZaP, Slicer, or XYZ window. This readout shows the byte value from program memory unless you turn on a checkbox to have it show values from the image file. Model View Window This window shows the model in 3D, continually updated as the model is edited. The window behaves the same as when it is started with the 3dmodv command, except that some menu items are unavailable. See the manual page for 3dmodv. SURFACES, OPEN CONTOURS, LABELS, AND POINT SIZES Several features can be controlled from the Surf/Cont/Point window. One is the surface, which is an optional level of organization between contours and objects. With surfaces, one can keep track of, navigate between, and manipulate groups of contours without having to use a sep- arate object for each group. Each contour in an object has a surface number, which is 0 if surfaces are never employed. To start a new sur- face, use N or the New Surf button in the Surface section of the window to obtain a new, empty contour with the new surface number. There- after, each new contour will have the same surface number as the previ- ous contour being modeled, until a new surface is started again. The Surface section of this window has controls for moving within and between surfaces and for visualizing contours of the current surface, using the Ghost button. The Contour Move window has options for moving contours from one surface to another or for moving an entire surface to a new object. The Contour section of the Surf/Cont/Point window has radio buttons for defining individual contours as open in an object defined as having closed contours. This is useful for displaying a partially cut edge of an object. See imodmesh for more details. This part of the window also has a text box for displaying and editing the time index of the current contour. If you have loaded multiple image files and want to model contours at specific times (i.e., dis- played only on images from a specific file), you must first activate time editing with a button in the Edit-Object-Type window. Once this feature is selected, newly created contours will be assigned to the currently displayed time. The Point section of the Surf/Cont/Point window has a text box and slider for assigning a size value to an individual point. Any point with an individual size will be displayed as a sphere, just like points in scattered point contours. The window also has text boxes in which one can enter labels for indi- vidual contours and points. The Section Ghost section of the Surf/Cont/Point window has controls to enable the display of ghost contours from adjacent sections, which is also toggled by the g hot key. Ghosts can be displayed from above or below the current section, and from variable numbers of sections away, or simply from the nearest section having contours in the particular object. There are also options to control whether the ghost contours are lighter or darker in color, and to show ghosts from all objects rather than just from the current object. AUTOSAVE AND BACKUP FILES The program will back up the current model to the file model_file_name#autosave# every few minutes. If no model file has been saved yet, the name of the autosave file is just #autosave#. The autosave file is eliminated whenever the model is saved, and when the program exits normally. The first time that you save a model file, the existing model file will be renamed to model_file_name~, and any exist- ing file by that name will be deleted. This backup file will not be overwritten each time that you save thereafter, so that it will pre- serve the state of the model when 3dmod was started. Automatic saves can be controlled or disabled by using the 3dmod Pref- erences dialog or by setting environment variables (obsolete). The Preferences dialog has a checkbox to enable autosaving, a spin box to set the number of minutes between automatic saves, and a text box to specify a directory in which the autosave file will be written. Thus, one can specify a directory on a local disk (e.g., /usr/tmp) and avoid the long delays required to write a large model to a disk over the net- work. Formerly, these features were controlled by the IMOD_AUTOSAVE environment variable, which specified the minutes between autosaves or 0 to disable autosaving, and by the IMOD_AUTOSAVE_DIR variable. If these variables are defined, the Preferences dialog will initially show their values; but once the user has changed these settings through the Preferences dialog, the environment variables will be ignored. IMAGE LIST FILES An image list file can be entered instead of an image file on the 3dmod command line. This ASCII file can specify a series of image files that represent different times, so that one can step through time as well as X, Y, and Z. An image list file can also be used to specify both an image file and a piece list with a single file. In either case, the cache is turned on. Lines beginning with # are treated as comments and ignored. The format of the file is: IMOD image list [must be the first line of the file] VERSION 0 or VERSION 1 [must appear somewhere in file] To specify a series of files at different times, include a series of entries of the form (the second entries for time labels are optional, and default label if it is omitted is the image filename): IMAGE image_filename TIME time_label [The label can be any desired text] If the first file might not exist, precede the list of images with a line: SIZE nx,ny,nz [nx,ny,nz are the image dimensions to be assumed for the first file] To specify an image file and piece coordinates, include the following: IMAGE image_filename XYZ [on a line by itself] x y z [piece coordinates, one line per section] . . . To load files that are located in another directory, include the fol- lowing before the IMAGE lines for the respective files. This entry can occur more than once. IMGDIR path_to_image_directory PLUGIN ENVIRONMENT 3dmod will load special plugin libraries that are in the directory pointed to by the IMOD_PLUGIN_DIR environment variable. If IMOD_PLUG- IN_DIR is not defined, the program will search in IMOD_DIR/lib/imodplug if IMOD_DIR is defined, or in lib/imodplug under the default installa- tion location for the operating system if IMOD_DIR is not defined. In addition, the directory defined by $IMOD_CALIB_DIR/plugins, as well as the directories /usr/local/IMOD/plugins and /usr/freeware/lib/imod- plugs/ are searched for plugins if they exist. Plugins work in all supported operating systems. To write your own plugins, see the IMOD library documentation and use the old version of the Bead Fixer plugin as an example. The best place to place custom plugins would be /usr/local/ImodCalib/plugins. AUTHORS Jim Kremer David Mastronarde SEE ALSO Viewing programs 3dmodv, midas Model conversion imodinfo, imod2vrml Image conversion tif2mrc, raw2mrc, dm2mrc, mrc2tif BUGS Please email all bug reports to mast at colorado dot edu. BL3DEMC 4.3.7 3dmod(1)