3dmod

3dmod(1) General Commands Manual 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 when opening an existing model, in
 which case 3dmod will draw the model on top of blank images. A text
 file containing a list of image files can be used in place of the image
 file names on the command line. The name of a directory containing a
 single image list file (with a name ending in "list") can also be
 entered in place of the image file names. Ordinarily, if multiple
 files of different sizes are loaded, then the size of the display in
 each dimension will be set to the maximum size of the various files,
 with smaller images centered in the display. However, it is possible
 to enter a set of files that form an "image pyramid", i.e., copies of
 the same volume at different resolutions, in which case 3dmod will
 behave essentially as if only the highest-resolution volume was being
 displayed. 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 and files to be
 chosen.
 In Windows, 3dmod expands wildcards ('*' and '?') for input filenames
 internally, which is particularly useful without Cygwin. It can also
 be used in Cygwin when the command line is too long after expansion;
 enclose the names with wildcards in quotes to keep the shell from
 expanding then.
 File Formats, Image Types, and Related Restrictions
 Images can be in the MRC image format; in the TIFF format; 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, Winkler's FFF format, PIF files produced by Bsoft,
 DigitalMicrograph version 3 and 4 files, and FEI/TFS raw files with
 floats or short integers. 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 distributed with
 IMOD. TIFF files with EER (Electron Event Representation) compression
 can also be read with a selected amount of super-resolution and summing
 of frames (see the -es and -ez options). Raw files can be read if
 their dimensions, data type, and header size are defined. This infor-
 mation 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. Finally, a series of numbered TIFF
 files saved by SerialEM and listed in a metadata file (an ".idoc" file)
 can also be read just like an image stack.
 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. Several other restrictions on image files exist. The
 file-reading modes in 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,
 the Tumbler and Graph windows cannot be opened. Multiple montages can-
 not be opened unless they are part of an image pyramid.
 The Full-slice Image Cache
 Images are loaded as whole Z slices into an image cache under certain
 circumstances: whenever more than one file is specified (except as an
 image pyramid), 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. The program will also use the cache when a single image
 file would require more than 3/4 of the system memory (or of the
 addressable memory of 4 GB, for a 32-bit version), limiting the cache
 to that size. (An environment variable, 3DMOD_MEMORY_LIMIT, can be set
 to control this limit; see imodenv.) 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 implica-
 tions that are mentioned below. Starting a movie through the images
 will eventually load as much data as will fit into the cache. In addi-
 tion, there is a dialog box to fill the cache in various ways, avail-
 able through the Edit-Image-Cache Filler menu entry. If any files
 other than MRC-type (MRC or raw) or HDF are loaded, the image volume
 cannot be rotated around the X axis (with Y and Z sizes swapped) unless
 it is fully loaded into the cache.
 The Tile/Strip Image Cache and Image Pyramids
 An image pyramid can be used to get rapid access to subareas of a large
 image volume, at any zoom, without having to load the entire volume
 into memory. To provide such access, 3dmod sets up a different kind of
 cache that is organized in either image strips or in tiles. If the
 image file is itself tiled (a montaged MRC file, a tiled TIFF file, or
 a chunked HDF file), then the cache contains tiles loaded from the
 file; otherwise the cache is organized as strips across the whole width
 of the image and with a height that will make each strip about 1
 megapixels in size. The advantage of having the cache organized as
 tiles is that when you want to display a subarea, the program can load
 just the tiles tha intersect the subarea, and each tile can be read
 quickly because it is stored contiguously on the disk. If the file is
 not tiled, there is still some advantage in having a strip-based cache
 for a large file, because only a subset of a slice has to be loaded
 instead of the whole slice. Thus, any large-area file can be opened
 and viewed more quickly by opening it with the -CT 0 option. However,
 if you zoom down to see the whole image, the program will still have to
 load the entire slice for each section that you step to. The only way
 to speed that up is to make an image pyramid, so that a lower-resolu-
 tion file can be accessed quickly when you are zoomed down. An image
 pyramid can be created easily with Makepyramid.
 There are two ways to indicate that a set of images comprise a pyramid:
 by entering the option -py and by using an image list file with a
 "PYRAMID" line. If the files include more than one montage, these
 entries are not needed, because multiple montages are allowed only for
 a pyramid. The image files, and any associated piece list files for
 montages, can also be listed either at the command line or in an image
 list file. Makepyramid provides a complete image list file for dis-
 playing the pyramid that it creates. When opening an image pyramid, it
 is not necessary to enter the -CT option unless you need to limit the
 size of the cache. When this option (or the -C option) is not entered,
 the default limit on the cache size is 20000 MB (20 GB); this limit can
 be changed by setting an environment variable TILECACHE_LIMIT_MB to a
 different value in megabytes. For a given set of files, the limit is
 reduced to what is needed to load all files fully. The tile/strip
 cache is allocated dynamically, with memory requested from the system
 only when needed, unlike the slice-based cache, where all memory is
 allocated on program startup. The different behaviors of the program
 when using the tile/strip cache or an image pyramid are described
 below, after the main windows and other operations have been intro-
 duced.
 Windows
 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, Multi-Z, Tumbler, Graph, Pixel View, Locator, and Model
 View windows.
 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 Multi-Z Windows is a variant of the ZaP window that displays an
 array of images at the same location and different Z values.
 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, Multi-Z, 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. Also, 16-bit files may be
 loaded as integers despite this entry if the files have no scal-
 ing information, depending on choices in the Scaling panel of
 the 3dmod Preferences dialog. 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, isosurfac-
 ing, 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.
 -es value
 Read EER files with the given amount of super-resolution. Enter
 0 for data binned into physical pixels with no super-resolution,
 1 for a 2x2 super-resolution, and 2 for 4x4 super-resolution.
 Negative numbers are also allowed for images reduced with
 antialiasing directly from the super-resolution electron posi-
 tions: -1, -2, and -3 reduce by 2, 4, and 8. The entered number
 overrides the value set in the 3dmod Preferences dialog, whose
 default is 1.
 -ez value
 Enter the number of consecutive frames to sum into groups when
 reading EER files, or the negative of the number of groups
 (summed frames) to read. Unlike binning, this summing happens
 as efficiently as possible in the TIFF reading module. When a
 positive summing value does not evenly divide the total number
 of frames, the specified frame summing is the maximum summing
 that will occur, and the frames will be distributed as evenly as
 possible, with the summing lower by 1 at the beginning of the
 stack. The entered number overrides the value set in the 3dmod
 Preferences dialog, whose default is 10.
 -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.
 -ic X,Y,Z
 Set the starting current image point, and the center coordinate
 for an initially opened Zap and/or Slicer window, to the given
 X, Y, Z values. Both center coordinates and angles (-ia option)
 must be entered to initialize a Slicer window.
 -ia X,Y,Z
 Set the angles for an initially opened Slicer window to the
 given X, Y, and Z values.
 -iz value
 Set the zoom for an initially opened Zap and/or Slicer window to
 the given value.
 -it value
 Set the tilt angle for the image shown first when 3dmod opens,
 if the option to start at the middle Z is set in the 3dmod Pref-
 erences dialog.
 -Y This option causes the image data to be rotated by 90 degrees
 around the X axis 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/Rotate. 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 single-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 an entered number of
 images to be loaded into a more flexible memory cache that holds
 full slices when needed. Alternatively, one can limit the size
 of the cache in megabytes by entering a value with m or M on the
 end. or in gigabytes by using a g or G on the end. For example,
 -C 12G will limit the cache to 12 gigabytes. 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.
 -CT value
 Load any file as tiles or strips into a tile/strip cache, as
 described in other sections. The entered value controls the
 maximum size of this cache, expressed as a number of sections or
 in megabytes, if followed by 'M' or 'm'. The option is not
 needed when loading an image pyramid, except to provide a limit
 for the size different from the default of 20 GB.
 -F Fill the full slice 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. It is not necessary to use this option if there are
 piece coordinates either in the extended header of an MRC file
 or in a metadata autodoc (.mdoc) file created along with an MRC
 file by SerialEM (provided that the file is present in the same
 directory).
 -pa filename
 Load a file with aligned piece coordinates produced by Blend-
 mont(1) when it made the blended input image file. With the
 information in this file, if the current point is placed in the
 middle of a particular overlap zone, and the Ctrl-E hot key or a
 message from Midas can be used to obtain the piece and edge
 numbers for displaying the edge in Midas.
 -py The multiple image files form an image pyramid of the same vol-
 ume at different resolutions.
 -A value
 Use aligned piece coordinates from a metadata autodoc (.mdoc)
 file when loading a montage. When SerialEM determines the
 alignment between montage pieces for display there, it stores
 adjusted piece coordinates in the .mdoc file. Separate values
 are stored for alignments done with and without the "Treat as
 very sloppy montage" option turned on. Enter a value of 1 or 2
 to use these aligned coordinates if they are present (and if the
 .mdoc file is present in the same directory). With a value of
 1, 3dmod will use coordinates without the "very sloppy" option
 if avauilable, then ones with that option, then the nominal
 coordinates if neither are present. With a value of 2, it will
 seek coordinates with the option, then ones without. A default
 value for this option can be set in the 3dmod Preferences dia-
 log. A value of 0 here can be used to override the default set
 there.
 -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 or an asso-
 ciated metadata autodoc (.mdoc) file 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.
 -J value
 Set the type of scanning to use to determine scaling limits when
 reading a raw file, or when reading a file that does not have
 proper information for setting the scaling. The value should be
 0 for a full scan for the minimum and maximum, 1 for a scan of
 subsets to estimate the min and max, or 2 for a scan of subsets
 to estimate the mean and standard deviation (SD). The subsets
 will be ~1 MB and the interval between subsets will vary between
 ~9 and ~11 MB. This entry overrides whatever default is set in
 the Scaling panel of the 3dmod Preferences dialog, available
 through the Edit-Options men entry. When the mean and SD are
 used for scaling, data are truncated at white and black a cer-
 tain number of SDs from the mean; 6 by default, but changeable
 in the Preferences dialog.
 -K Store the results in the file header when scaling limits are
 determined by scanning an MRC file. When minimum and maximum
 are determined, the mean will be set to an invalid value if it
 was invalid before. If the min and max are just estimates from
 a subset, somewhat more widely spaced values will be placed in
 the header. When mean and SD are determined because min and max
 are not available, the min and max will be set to invalid values
 that are below the mean. This entry overrides the default
 selected in the Scaling panel of the Preferences dialog.
 -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 rotated around X 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, or
 load an MRC volume stack as a single stack instead of multiple
 volumes. By default, single-image files become multiple sec-
 tions in Z instead, and this option is useful for seeing their
 names. An MRC volume stack, defined by having the "space group"
 401 as well as by having a z sampling or "grid" value in the
 header listing less than the number of sections, is loaded as
 multiple volumes at different time values. This option is
 needed to load one as a single stack instead. A file can be des-
 ignated as a volume stack with the -volstack entry to Alter-
 header.
 -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 or any other 24-bit color file in
 gray-scale rather than in color. Use this option to display
 color and and gray-scale files together in gray-scale.
 -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, 4 for Draw-
 ing Tools, 5 for Interpolator, 6 for Bead Helper, 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, R), or with D
 for depth cue and S for stereo. Two key numbers are for other
 operations: 1 to start in model mode, 2 to suppress query to
 save model when exiting. If this option is entered multiple
 times, the strings of key letters will be combined into one.
 -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. Also the M key
 letter will turn off multisample antialiasing in Model View.
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
 (or just "3dmod - Preferences" on the Mac). 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/.config/BL3DEMC/3dmod.conf. Only those properties 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 program manages most of the tool windows by docking them in a stack
 attached to the window from whose menu they are opened (the Information
 Window or Model View Window, referred to as the master window in this
 description). Each such dialog has a "+/-" button at the top to col-
 lapse the dialog to one line or reopen it, and a "?" button to open
 its help page. Here are the rules governing this dock:
 1) Dialogs are stacked from the top of the screen down, first in a
 column that can contain the master window in the middle (if there is
 room both above and below it), then in adjacent columns that are added
 in the direction farther from a screen edge.
 2) A newly opened dialog is added to the end of the stack.
 3) The stack is rebuilt, and dialogs may move from one column to
 another, when the master window is moved or when any window (including
 the master one) is resized.
 4) By default, all windows in the stack will raise when one of them
 gets the input focus, providing an easy way to access dialogs that have
 fallen behind other windows.
 5) Moving a dialog away from the stack will detach it so that it is
 no longer managed in this way. A dialog in an interior column would
 need to be moved completely outside the stack, while one on the edge of
 the stack can be detached by moving it laterally a few pixels.
 6) A detached dialog can be reattached to the stack by moving it so
 that it overlaps or touches other windows. The dialog can be inserted
 in the middle of a column by positioning the middle of its title bar
 within the column and in the bottom half of the window to add it after,
 or in the top half of the window to add it before. A dialog can gener-
 ally be attached to the top or bottom of a column by moving its edge up
 against the edge of another window in the stack.
 7) There are menu entries to save the current state of the docked
 windows, and to reopen those windows in the same state.
 8) If docked dialogs have gaps or overlap, this spacing can be fixed
 by adjusting the assumed dialog border size in the Windows panel of the
 3dmod Preferences dialog, which also has options to control whether
 windows raise each other.
 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 on using 3dmod with a high-DPI monitor is provided in sec-
 tion 1.13 of the IMOD Guide.
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 Zap or Slicer window, with rotation around X 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; or move meshes from one isosurface object
 to another.
 Combine Combine all objects in which a contour is selected
 into one object and delete the other objects; or
 combine a set of selected isosurface 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/Rotate Rotate around X, swapping 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.
 Save Dock Save the current list of docked dialogs and their
 open/closed state in settings.
 Reopen Dock Reopen and restack dialogs to recreate the previously
 saved state.
 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. (\)
 Linked Slicers Open an array of slicers, one per image file, with a
 single toolbar to control the slice
 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. Five
 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; Interpolator to generate contours automat-
 ically between ones that you draw; Name Wizard to help with systematic
 naming of model structures; and Stereology to provide tools for making
 quantitative estimates by stereology.
 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 - (Zero) Create a new object
 Delete - Delete current model point
 D - Delete current contour or all selected contours
 Ctrl-D - Truncate current contour at current point
 Ctrl-Shift-D - Delete current surface
 M - Move contour to selected object or surface
 k - Copy contour (when Contour Copy dialog is open)
 J - Join two selected contours
 Ctrl-B - Break contour (when Contour Break dialog is open)
 O - (Shift o) Switch selected contour(s) between open and closed for
 a closed-type object
 Ctrl-G - Toggle showing a gap between current and next point.
 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
 = or + - Increase Zoom (except in Slicer, where Keypad + works
 instead of +)
 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
 Ctrl-Shift-A - Select all contours in any 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
 q - Report the distance from the current image or model point to the
 cursor
 R - Resize window to size of image or rubber band
 P - Activate moving current contour with first mouse button, rotating
 it with the second, or stretching it with the third.
 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
 ------------------------------------------------------
 PageUp - Increase Z
 PageDown - Decrease Z
 Shift-PageUp - Increase Z to next section with contours in current
 object.
 Shift-PageDown - Decrease Z to previous section with contours in
 current object.
 Keypad-Star - Increase Z by the big paging step size, adjustable in
 Behavior panel of Options dialog, with default 10.
 Keypad-Slash - Decrease Z by the big paging step size.
 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 (this may be Help key on Mac
 keyboard)
 Shift-Home - Go to middle Z of stack - use this or Apple-Help on
 Mac if Help key opens Help
 1,2 - Previous,Next Time Index
 !,@ - Go to first or last time index, or to Start or
 End value for Time shown in File - Movie/Montage
 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 its original X, Y and Z axes. A
 fourth slider can be used to scroll through slices at the same orienta-
 tion. A cluster of arrow keys provides a more intuitive way to rotate
 the volume, by steps around the current X, Y, and Z axes. In the mid-
 dle of this cluster is the Shift Lock (Sh) button, which toggles a mode
 in which mouse buttons and keypad keys can be used to rotate the volume
 in the same way, without holding down the Shift key. The plus and
 minus buttons change the step size for these rotations. A small display
 on the right 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 pro-
 jected onto the slice.
 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 Rubber band button allows one to draw a rectangle to define an
 area to be extracted from the image file, or captured in a snapshot.
 The Arrow button allows one to draw a single, thick arrow for point-
 ing out a feature in a snapshot
 The FT button toggles between showing an image and an FFT of the
 image.
 The Z-Scale button determines whether the model's Z-scale will be
 applied to stretch the volume in the Z dimension and compensate for
 thinning or anisotropic pixel size.
 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 Help button opens up on-line help.
 The keyboard and mouse can also be used to rotate the volume 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
 B - Toggle rubber band on or off
 l - Show slice in ZaP and XYZ windows
 k - Toggle centering mode between new mode and classic mode
 q - Report 3-D distance from current image or model point to cursor
 position.
 R - Resize window to area enclosed by rubber band.
 s - Save model to 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 all three planes; see the on-
 line help for details on modeling effectively in planes other than XY.
 One can movie through one or more of the planes simultaneously. The
 toolbar has sliders that allow one to set the X, Y, or Z coordinates.
 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
 k - Center images on the current point as closely as possible
 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
 q - Reports the distance between the current image or model point
 and the mouse cursor
 PageUp/PageDown - These keys move up or down by one XZ or YZ plane when the
 cursor is in the XZ or YZ panel; elsewhere they
 move by one XY plane.
 Arrows - These keys move the current point laterally in the panel
 where the cursor is located
 Keypad-Ins - In model mode, provides a substitute for the second mouse
 button.
 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 any of
 the three planes will select that point as the current model
 point. Clicking 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 any plane will add
 a point to the current contour, provided it does not make a pla-
 nar contour non-coplanar.
 Dragging with the second mouse button depressed will add a
 series of points to the current contour.
 Clicking with the third mouse button in any plane will move
 the current model point to that location.
 Dragging with the third mouse button in any plane will con-
 tinously modify existing points until the end of the contour is
 reached.
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.
PROGRAM OPERATION WITH AN IMAGE PYRAMID OR TILE/STRIP CACHE
 There will be noticeable differences in program behavior when using an
 image pyramid or the tile/strip cache, unless data have been loaded
 fully into the cache. The best performance will be seen when using the
 ZaP window. To display its image, the ZaP window requests that tiles
 be loaded, if necessary, from a file at the best resolution for the
 current zoom, and covering an area about twice as large as the area
 being displayed. Thus, most panning can occur without having to load
 new tiles. Tile loading occurs asynchronously: the ZaP window will
 first show whatever part of the image is currently available, then its
 display will be updated as new tiles are loaded.
 As with the slice-based cache, windows that access data in 3D not
 located on the current Z slice will generally show black (0 values) for
 parts of the volume that are not currently loaded. When the tile/strip
 cache is used, each of these windows (except the Tumbler) has a button
 to fill the cache for the subarea displayed in the window. The cache
 will be filled for the whole extent in Z, or for as much as fits. Note
 that the Slicer, the Isosurface, and the Tumbler displays all access
 only full-resolution data. Thus, the button in the XYZ window toolbar
 and the "Fill" button at the bottom of the Model View Edit Image dialog
 will load data that depends on the zoom of the respective display.
 while the button in the Slicer toolbar and the "Fill" button at the
 bottom of the Isosurface dialog will load full-resolution data. The
 Edit-Image-Fill cache command can also be used to fill the cache. It
 picks which resolution to load, and the subarea, by considering first
 the Isosurface display, if any, then the image display in Model View,
 if any, then the display in the top Slicer, XYZ, or ZaP window. Even
 with an image pyramid, filling the cache may take some time for a thick
 volume. The operation is done asynchronously and other things can be
 done before it is finished.
 If you have very large images where it can take seconds to load a
 slice, it is important to be aware of which operations will load a
 whole slice or a significant fraction of one. The Locator always dis-
 plays the full image area, and the image display in Model View does so
 when opened; this is quick if there is an image pyramid and potentially
 quite slow otherwise. The Graph window loads full-resolution data for
 the region potentially included in the graph. This region would usu-
 ally be the whole width in X when the window is opened, but it can be
 restricted in advance by drawing the rubber band around the current
 point. Autocontouring by thresholding (Edit-Contour-Auto), the Line
 Tracker, and the livewire tool in Drawing Tools plugin all require full
 loading of the current slice at full resolution. Loading a large sub-
 area of interest with the -ix and -iy options may be needed to use
 these tools effectively.
 Some things will not work when using the tile/strip cache: image
 rotate/flip, image reload, image process, the cache filler dialog, and
 histograms in the graph window. Autocontrasting and floating may
 behave a little differently, especially for zoomed-down views of noisy
 data.
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 delays required to write a large model to a disk over the network.
 The dialog also has two checkboxes to speed up the saving: one to omit
 meshes generated on the contours of ordinary drawn objects, which are
 easily recreated, and one to omit the meshes of objects saved from the
 Isosurface dialog. The latter is a separate choice because such meshes
 may or may not be easy to regenerate. If there are no isosurface
 meshes, omitting the regular meshes can speed up the saving by a factor
 of 4.
 Formerly, the autosave 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. A series of image files can form an image pyramid
 instead. 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 1 or VERSION 2 [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 without including
 the path on the IMAGE line, include the following before the IMAGE
 lines for the respective files. This entry can occur more than once.
 IMGDIR path_to_image_directory
 The following entries are allowed only in version 2 files, readable in
 IMOD 4.6.19 or higher.
 To indicate that multiple files form an image pyramid, include a line:
 PYRAMID
 The image files for a pyramid can be entered in any order.
 To specify a file with coordinates of pieces to associate with the last
 entered image file, include a line:
 PIECEFILE piece_list_file
 To specify X, Y, and Z origin values for the last entered image file,
 include a line:
 ORIGIN X_origin Y_origin Z_origin
 This entry provides a way to retain the origin values for a TIFF value
 that was converted from an MRC file; it will override the origin values
 for an MRC file.
 To specify lower and upper intensity scaling limits (equivalent to the
 -s option) for image files that occur after this point, include a line
 SCALE lower_limit upper_limit
 This entry can occur more than once.
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, the direc-
 tory Plugins under $IMOD_DIR or the default installation location, as
 well as the directories /usr/local/IMOD/plugins and /usr/free-
 ware/lib/imodplugs/ 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; also see Andrew Noske's plugins. The best
 place to place custom plugins would be /usr/local/ImodCalib/plugins (or
 $IMOD_CALIB_DIR/plugins if that is different). If an IMOD installation
 has a Plugins directory, the IMOD installer will copy its contents to a
 Plugins directory when upgrading to a new version, so this is the one
 option for keeping plugins inside IMOD and having them preserved upon
 upgrade.
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.
IMOD 5.2.0 3dmod(1)