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.

   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,
       and DigitalMicrograph version 3 and 4 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
       distributed with IMOD.  TIFF files with EER (Electron Event Representa-
       tion) compression can also be read with a selected amount of super-res-
       olution 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 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.  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.  By default, the cache will be fully loaded upon program
       startup and the program will behave the same as with regular data load-
       ing.  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.  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.
              The entered number overrides the value set in the 3dmod Prefer-
              ences dialog, whose default is 1.

       -ez value
              Sum groups of the given number of consecutive frames when read-
              ing EER files.  Unlike binning, this summing happens as effi-
              ciently as possible in the TIFF reading module.  When the sum-
              ming 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.

       -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.  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.

       -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).

       -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
              (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 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 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.  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 6.16.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
       enetered 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                                4.11.0                            3dmod(1)