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)