3dmod(1) 3dmod(1)
NAME
3dmod - Make a model from a 3-D image stack.
SYNOPSIS
3dmod [options] [image filenames] [model filename]
DESCRIPTION
3dmod is typically invoked with one image file, but multiple image
filenames can also be given. The model filename is optional; if 3dmod
is called without a model file it will create a new model. The user
can load new model files using a menu selection once 3dmod is running.
If the model file does not already exist, 3dmod will create a new model
under that name. The image files may also be omitted, in which case
3dmod will draw the model on top of blank images. A file containing a
list of image files can be used in place of the image file names on the
command line. If multiple files of different sizes are loaded, then
the size of the display in each dimension will be limited to the mini-
mum size of the various files. 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.
The model must be in the IMOD model format. Images can be in the MRC
image format; in the TIFF format, if the appropriate TIFF library is
available; in any of the formats supported by the Qt image-reading
function, which include JPEG, PNG, PPM, and BMP; or in a raw format
where data are packed sequentially as in MRC files. Some kinds of raw-
type files will be recognized automatically and and treated like MRC
files. These include Hegerl's EM format, Winkler's FFF format, PIF
files produced by Bsoft, and DigitalMicrograph version 3 files. MRC
files of almost any mode can be read in: byte, 16-bit integer, real,
complex real, complex integer, or color (RGB). TIFF files may be byte,
16-bit integer, or color, where the color can be either 24-bit (RGB) or
8-bit using an embedded color map. TIFF files may be organized in
strips or in tiles, and files with various kinds of compression can be
read, depending on the capabilities of the libraries on the system.
Raw files can be read if their dimensions, data type, and header size
are defined. This information can be provided with the options -r, -t,
and -H or through a dialog box that is brought up when a file is
encountered that cannot be read by other means.
When multiple files are read in, they usually do not need to be the
same mode or even the same format. The exceptions are that if any file
is an RGB file, all files must be, and if any file has a colormap, all
files must. Images are loaded into an image cache under certain cir-
cumstances: whenever more than one file is specified, when montaged
data are loaded, 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. Several other restrictions on image
files exist. If any files other than MRC-type (MRC or raw) are loaded
and the cache is used, the image volume cannot be flipped (Y and Z
exchanged) unless it is fully loaded into the cache. The Pixel View
window, high-resolution mode in the Graph window, and the f and F hot
keys for finding pixel values will all give zeros for a non-MRC type
file. If RGB files are loaded, only the Zap and Model View windows can
be opened.
Two windows will open upon startup: the Information Window and an image
window. The Information Window is the main control window; it has a
menu bar and has indicators that give information about the selected
model point and the selected graphics voxel. The bottom of the infor-
mation window also has a status box that shows the progress of certain
operations while using 3dmod. While the image is loading, the Informa-
tion Window will report the status of the image load. Selecting the
Quit menu item from the File menu will cancel the image load. If the
image cache feature is used, the image window will open up after the
first image section is loaded; otherwise, the image window won't open
until the entire image has been loaded.
The ZaP Window is the default image display window used by 3dmod. It
allows one to view an image at any magnification and to pan the image
around inside a resizable window. Most manual model editing is done
within the ZaP Window.
Additional windows that may be opened via menu selection are the
Slicer, XYZ, Tumbler, Graph, Pixel View, Locator, and Model View win-
dows.
The Slicer Window allows one to view slices through the 3-D image
data. If the image cache is turned on, only images in the cache will
be displayed in views that contain data from multiple Z sections.
The XYZ Image Window displays slices of the 3-D image in planes per-
pendicular to the X,Y and Z axis.
The Tumbler Window allows one to view a small projected view of the
area around the current point.
The Graph Window graphs intensity along a given axis or along a
given contour.
The Pixel View Window shows the actual pixel values from the image
file around a given point.
The Locator Window shows the whole image area and a box that allows
you to see and change the subarea shown in the ZaP window.
The Model View Window views the model in a 3D rendering while it is
being built.
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 displayed as black (0) and white
(255) on the screen. Without this option, intensities are
scaled between the minimum and maximum intensities in the image
file. 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 prevent them from being scanned for their minimum and
maximum values.
-xyz This option causes the default image window to be the XYZ window
instead of the ZaP window.
-S This option causes a slicer window instead of the ZaP window to
be opened when the program starts.
-V This option causes a model view window instead of the ZaP window
to be opened when the program starts.
-Z This option causes a ZaP window to be opened even if one of
-xyz, -S, or -V is entered. These 4 options can all be used
together to open a selected set of windows.
-Y This option causes the image data to be flipped after it has
been loaded. This allows one to model image planes that are
normal to the Y-axis. The default is to model planes normal to
the Z-axis. It is possible to flip back and forth between these
two modeling orientations using the Edit Image menu item Flip.
Certain cached data can not be flipped unless they are entirely
loaded into memory: TIFF files, montaged images, images loaded
with different binning in Z than in X and Y, and multiple sin-
gle-image files.
-h -help
Print some quick help for 3dmod's command line options to the
terminal.
-O Open the startup dialog box for setting program options and
selecting files. The box will be filled in with any other argu-
ments included in the command line.
-C <value>
The -C option controls the image cache used by 3dmod. By
default, 3dmod will try to load the entire image into an ordered
array in memory. This option can force a given number of images
to be loaded into a more flexible memory cache. Alternatively,
one can limit the size of the cache in megabytes by entering a
value with m or M on the end. For example, -C 200M will limit
the cache to 200 megabytes. The reason for using this option is
either to decrease start up time or to view large data sets that
can't fit into main memory. This features works best with the
ZaP Window, which always loads the image that it needs into the
cache. Other image windows will only be able to access image
data that are already within the cache. As a special case,
entering -C 0 will set up a cache that is large enough to hold
all image data but will load images only when needed.
-F Fill the image cache upon program startup, before displaying any
images. This option is useful if you will be using the Slicer
or XYZ windows, to avoid seeing incomplete slices. This flag is
not needed unless you define the size of the cache with the -C
option.
-p <filename>
Load a file containing a piece list for the input image. This
allows one to montage image sections together or to view images
that are either missing sections or have sections out of order.
The piece list is an ASCII text file with the following format.
There are as many lines as the input image has frames (the z
dimension of the image file). Each line contains three values
<X> <Y> and <Z> which represent the starting location of each
frame in the input image stack. Using the piece list option
will also turn on the image cache with a default size equal to
the total number of image z-planes that contain data. The image
cache can't be turned off, but the size can be changed with the
-C option.
-P <nx,ny>
Create an internal piece list to display images from the file in
a montage of nx by ny pieces. If an external piece list file is
entered with the -p option, then this option is ignored; with
this option, montage information in the file header is ignored.
-o <nx,ny>
When creating an internal piece list with the -p option, set the
overlap between pieces to nx in the X direction and ny in the Y
direction. Enter negative numbers to get space (gutters)
between the pieces.
-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.
-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.
-f Load file as individual frames, overriding montage information
in the image file header. It is possible for an image file to
have piece coordinates stored in its header rather than in a
separate piece list file. 3dmod will automatically load such a
file as a montage, so this option is available to override this
behavior and force loading as individual frames.
-m This option overrides the model transformation behavior and
causes the model to be loaded without any transformations. This
option is useful for loading an existing model onto a data stack
after it has been flipped in Y and Z or after the pixel size or
origin has been changed in the image file header.
-T Load multiple single-image files as files at different times
(the behavior before IMOD 3.2.3). By default, such files will
now become multiple sections in Z instead.
-M Load Fourier transform files without mirroring the data around
the origin. By default, a complex mode input file whose X
dimension is odd will be loaded with replication of the data on
the left side of the Y axis, to make it easier to visualize.
This option can be used override that behavior if it is inappro-
priate for the input file or if there is not enough memory to
show the redundant data.
-ci Display images in color index mode using a color table, rather
than in 24-bit color mode. Color index mode only has 8 bits and
works rather poorly under Qt.
-cm <file>
Read a specification for the false color map used in 3dmod from
a file. This file can have one of two forms. One form starts
with a line with 256, then has 256 lines with red, green, and
blue values from 0-255. The other form starts with the number
of lines to follow; then each following line has a red, green,
and blue value (0-255) plus an arbitrary integer indicating the
relative location of that value along the 256-color range.
These location values must be in order. If the colors being
specified are to be equally spaced, the location values can sim-
ply be sequential values.
-G Display an RGB-mode MRC file in gray-scale rather than in color.
If the list of files being loaded includes a color TIFF file,
all files will be displayed in color regardless of this option.
-view -modv
Either option will run 3dmod in model view mode, the same as
using the command 3dmodv to start the program. Only 3dmodv
options are allowed in this case.
-E <keys>
Open the windows specified by the key letters: t for Object
Type, l for Object Color, h for Model Header, o for Model Off-
set, s for Surf/Cont/Point, v for Contour Move, c for Contour
Copy, a for Auto Contour, b for Contour Break, j for contour
Join, p for Image Process, r for Image Reload, f for Image Cache
Filler, u for Tumbler, x for Pixel View, A for Slicer Angles, G
for Fine Grain. If the -V option is given, then model view dia-
log boxes can also be opened with key letters the same as their
hot keys (m, O, C, L, B, M, V, I), or with D for depth cue and S
for stereo.
-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
keystrikes.
User Interface Features
A large number of dialog boxes can be opened from the menus of the
Information Window and the Model View Window. Nearly all of these are
tool windows that can be left open while doing other tasks in the pro-
gram. These tool windows pass hot keys on to image windows, so that
one can use hot keys to perform actions in an image window without hav-
ing to make that window have the keyboard focus. Tool windows opened
from the Information Window menu will pass keystrokes on to the most
recently active image display window. Tool windows opened from the
Model View Window menu (i.e., 3dmodv dialog boxes) will pass keystrokes
on to the Model View Window.
Preferences for some aspects of the appearance and behavior of 3dmod
can be set and saved between sessions of the program, using the 3dmod
Preferences dialog box available through the Edit-Options menu entry.
Among other features, the font size and type and the style of the
interface may be changed, the size and color of marker points can be
adjusted, and custom zoom values can be defined. On Unix systems,
preferences are saved to the file $HOME/.qt/3dmodrc. Only those prop-
erties that the user has changed are saved to and restored from this
file, while properties that have never been changed will be set to the
current program defaults.
The 3dmod Preferences dialog also allows the function of the three
mouse buttons to be remapped in any desired way. Because of this flex-
ibility, mouse functions are described here and in the help windows of
3dmod in terms of the first, second, and third buttons. By default,
these correspond to the left, middle, and right buttons.
By default, the sliders in 3dmod are continuously active, or hot, which
means that the program will attempt to update the display as a slider
is dragged. If the program can not keep up well enough, the continuous
update can be stopped by pressing the Ctrl key while dragging the
slider. In the Preferences dialog, a different key can be selected to
control this behavior, and the behavior can be inverted so that sliders
are hot only when the control key is pressed.
Nearly all controls in 3dmod have tooltips that will appear when the
mouse pointer is left over a control for about half a second. These
tooltips can be disabled in the Preferences dialog.
Snapshots can be taken of image and model view windows with hot keys.
A TIFF snapshot can be taken with Ctrl-S. Snapshots in other formats
such as JPEG, PNG, and SGI RGB can be taken with Shift-S or Ctrl-Shift-
S. The format of these non-TIFF snapshots can be selected in the Pref-
erences dialog. There is an entry in the file menu that allows you to
select (and create) a directory in which snapshots will be saved.
The Escape key can be used to close all windows except the Information
Window, or the 3dmodv window when running 3dmodv.
Information Window
The Information Window is 3dmod's main control window and it is open at
all times while 3dmod is running. All other windows can be opened and
closed without restarting 3dmod.
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.
]/[ - 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.)
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 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 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.
Set Snap Dir... Set a directory to put snapshots into. The same
directory will be used for snapshots from the
model view window.
Write Model as Write model as Imod, wimp, NFF or Synu files.
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.
Quit Quit 3dmod.
Edit Menu
Model
Header... Set the model's Z-Scale for viewing, its pixel
size, resolution (spacing between points during
contour drawing), and whether the model is drawn
or not.
Offsets... Offset the model data in X, Y and Z.
Clean Delete all objects that contain no points (i.e.,
that have no contours, or only contours with no
points).
Object
New Create a new object. Opens Object Type dialog box.
Delete Delete current object, or all objects in which a
contour is selected
Type... Edit Object type.
Color... Open requester for changing object color.
Move... Move all contours from current object to another
object.
Combine Combine all objects in which a contour is selected
into one object and delete the other objects.
Info Calculate volume and surface area of current object.
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.
Surface
New Create a new contour with a new surface number. (N)
Go To... Select a different surface in the Surf/Cont/Point
window.
Move... Move contours in a surface to a different object or
a different surface using the Contour Move window.
Delete Delete the current surface, i.e. all contours with the
same surface number as current contour.
Contour
New Create a new contour. (n)
Delete Deletes the current contour. (D)
Move... Move current contour to a different object or
surface.
Copy... Copy contours to a different object, Z-level, or
time.
Sort Sort contours in a closed or open contour object by
their Z values and by their time values.
Break... Break contour into two contours. Closed contours
can have two break points.
Join... Join two contours together. Closed contours will be
joined at the nearest point; open contours will
be joined such that the joined contour will have
points up to the first selected point from the
first contour and from the second selected point
to the last point from the second contour.
Break by Z Break a closed contour at every change in Z,
creating as many contours as necessary so that
each lies in a single Z plane.
Fill In Z For an open contour that traverses through Z, add
points by interpolation to fill in any gaps where
the contour skips one or more sections.
Loopback Add points to the end of a contour so that it loops
back from its current end to its start along the
same path. Such a contour can be used to make a
complex cap over an elongated, oddly shaped
contour.
Invert Invert the order of points in the current contour.
Info Print area and/or length of contour.
Auto... Make new contours using threshold.
Type... Edit contour internal data, such as
surface #, time index and labels.
Point
Delete Delete Current point. (Delete)
Size... Set size of individual points.
Distance Show distance between current and last model
points.
Value Show current voxel value from image file.
Sort by Z Sort points in a contour by Z value.
Sort by dist Sort points in a contour by interpoint distance so
that the closest possible points are neighbors
Image
Flip Exchange Y and Z dimensions of the image data.
Process... Process images by filtering.
Reload... Open the image scale reload requester.
Fill Cache Fill the cache if there is one.
Cache Filler... Open a dialog box to control cache filling and
select autofilling.
Movies... Open window to control movie limits in X, Y, Z and
time.
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.
Options... Open 3dmod preferences dialog to personalize settings
Image Menu
ZaP Open a ZaP window. (Z)
XYZ Open the XYZ window.
Slicer Open an image Slicer window. (\)
Model View Open a 3dmod model view window. (v)
Pixel View Open window displaying pixel values.
Graph Open an image Graph window. (G)
Locator Open a window to show the ZaP window subarea.
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.
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
] - Go to previous point
[ - 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
{ - Go to first point in contour
} - Go to last point in contour
n - Create a new contour
N - Create a new contour with a new surface number
0 - Create a new object
Delete - Delete current model point
D - Delete current contour
M - Move contour to selected object
J - Join two selected contours
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 marker on/off
g - Toggle previous contour ghost draw mode
s - Save Model File
f - Print current pixel value in information window
F - Find the maximum pixel within 10 pixels and report its value
, - Decrease movie speed
- - Decrease Zoom
= - Increase Zoom
3 - Start or stop a movie through time in the forward direction
4 - Start or stop a movie through time in the backward direction
S - Snapshot image in window to file with primary non-TIFF
format
Ctrl-S - Snapshot image in window to TIFF file
Ctrl-Shift-S - Snapshot to second type of non-TIFF file
Other keys active in the ZaP window only
----------------------------------------
Ctrl-A - Select all contours in current object on section or
within the rubber band
b - Build a contour while in auto contour mode
a - Advance to and fill next section when auto contouring
u - Smooth a filled area when auto contouring
i - Toggle the modeling direction
Z - Toggle auto section advance on and off
B - Toggle rubber band on and off
I - Print information about window, image size, and offsets,
also bring the Information Window to the front
R - Resize window to size of image or rubber band
P - Activate moving current contour with first mouse button
Keypad Ins - Add point(s) in model mode, like second mouse button
Esc - Close ZaP window
Keys to control position or move current viewing point
------------------------------------------------------
Page Up - Increase Z
Page Down - Decrease Z
Up Arrow - Increase Y
Down Arrow - Decrease Y
Right Arrow - Increase X
Left Arrow - Decrease X
End - Go to Z = 1
Home - Go to Z = max
Insert - Go to middle Z of stack
1,2 - Previous,Next Time Index
!,@ - Go to first or last time index, or to Start or
End value for Time shown in Edit-Movies dialog
Keypad Arrows - Move current model point in model mode,
- Pan in ZaP window in movie mode.
Arrows - Pan in ZaP window in model mode
Window control keys
-----------------------------------------
\ - Open Slicer Window
v - Open Model View Window
G - Open Graph window
z - Open ZaP window
Slicer Window
Multiple Slicer Windows can be opened. Each Slicer Window shows a dif-
ferent slice through a 3-D volume. The Slicer window has two to four
movable toolbars. The large toolbar contains three sliders that are
used to select the orientation of the slice by setting the angles of
rotation of the data volume around the X, Y and Z axes. A small dis-
play next to the sliders gives a visual cue to the slice location.
This toolbar also has two spin boxes, one to select the thickness of
the slice being displayed, the other to select the thickness of model
that will be projected onto the slice. It also has a Help button to
open up on-line help.
The narrow toolbar at the top of the Slicer has the following buttons,
from left to right.
The Up and Down arrows adjust the magnification in the slicer dis-
play window.
The text box shows the zoom and allows one to type in an arbitrary
zoom factor.
The checkerboard button toggles between nearest neighbor and slower,
cubic interpolation.
The Lock button will keep the Slicer from changing its current posi-
tion when locked.
The Centering button toggles between the default mode in which the
window can be panned with the mouse, and a mode in which the current
image point is kept at the center of the window (referred to as 'clas-
sic' mode).
The Shift Lock (Sh) button toggles a mode in which mouse buttons and
keypad keys can be used to rotate the volume as if the Shift key were
held down.
The IM/FFT button toggles between showing an image and an FFT of the
image.
The Show Slice button will draw where the slice intersects the X- Y-
and Z-planes in the XYZ window, and the Z-plane in the ZaP window.
The Contour button sets the angles so that the current contour is
flat in the slice.
The Z-Scale control determines whether the model's Z-scale will be
applied to stretch the volume in the Z dimension and compensate for
thinning.
The orientation of the slice can also be adjusted by rotating the vol-
ume relative to the current axes rather than the original axes. With
the Shift key held down (or with the Shift lock toolbar button on), the
second mouse button will rotate the volume around an axis in the plane
of the slice and perpendicular to the direction of mouse movement. The
third mouse button will rotate in the plane of the slice, around the
center point.
One can model in the Slicer Window, using the first mouse button to
select the current point, the second mouse button to insert a point
after the current point, or the third button to modify the current
point. The second button can be held down to insert points continu-
ously. In movie mode, the first button selects the current point, and
the second or third buttons together with the Ctrl key start movies
forward or backward through the data, in a direction perpendicular to
the slice.
Hot Keys in the Slicer
-/= - Decrease/Increase zoom
_/+ - Decrease/Increase displayed image thickness
9/0 - Decrease/Increase displayed model thickness
s - Show slice in ZaP and XYZ windows
k - Toggle centering mode between new mode and classic mode
S - Snapshot to file with primary non-TIFF format
Ctrl-S - Snapshot to TIFF file
Ctrl-Shift-S - Snapshot to second type of non-TIFF file
W - Set angles so that current contour is flat in the slice
x/y/z - Align current and previous model points along X, Y or Z
axis
X/Y/Z - Align first and last points of current contour along
X, Y or Z axis
Numeric Keypad (no Shift)
4/6 - (Left/Right) Decrease/Increase last adjusted angle by 0.1
2/8 - (Down/Up) Decrease/Increase last adjusted angle by 0.5
1/3 - (End/PgDn) Decrease/Increase last adjusted angle by 15.0
0 - (Insert) Set last adjusted angle to 0
Numeric Keypad (with Shift key down or Sh button on)
4/6 - (Left/Right) Rotate volume around current Y axis
2/8 - (Down/Up) Rotate volume around current Y axis
9/3 - (PgUp/PgDn) Rotate in plane of slice
</> - Decrease/Increase step size for these rotations (,/. also
do this if Sh is on)
XYZ Window
The XYZ window displays three slices: through an XY plane in the lower
left, through a YZ plane in the lower right, and through an XZ plane in
the upper left. The intersection of the model with these planes will
be drawn. Marker lines and crosses indicate the position of the cur-
rent point and of the slices within the volume. Like the ZaP window,
the XYZ window can be resized, and the images can be zoomed with hot
keys and panned within their view boxes with the left mouse button.
Basic modeling capability is available in the XY plane. One can movie
through one or more of the planes simultaneously. In addition, the
marker lines have handles that can be dragged with the mouse to riffle
through images in a plane. Each marker line's color matches the color
of the border around the plane that is controlled by its handle.
Hot Keys in the XYZ Window
-/= - Decrease/Increase zoom
r - Toggle between low and high resolution display modes
P - Toggle on or off showing a projection of the current
contour in the XZ and YZ planes, and of a current
contour that is open in the XY plane
S - Snapshot to file with current non-TIFF format
Ctrl-S - Snapshot to TIFF file
Ctrl-Shift-S - Snapshot to second type of non-TIFF file
Mouse Buttons in the XYZ Window
Actions in Movie Mode:
Clicking the first mouse button will select the current
point. In one of the three image planes, this will generally
change the coordinates displayed in the other two planes.
Clicking in the horizontal gutter region occupied by the X
marker line will change the current X coordinate and the plane
displayed in the YZ panel. Clicking in the vertical gutter
region will select a new Y coordinate and XZ plane. Clicking in
the upper right region will select a new Z coordinate and XY
plane, as indicated by the crossed marker lines.
Dragging with the first mouse button depressed will either
pan the image within the window or riffle through one of the
planes, depending on where the mouse is when the button is first
pressed. If it is in one of the image panels, dragging will pan
the image (provided it is larger than the window.) In the hori-
zontal or vertical gutter regions, dragging will riffle through
YZ or XZ planes, respectively. In the upper right region, drag-
ging will change the XY plane; this is most effective if one
grabs the handle there and moves diagonally.
Clicking the second mouse button in one of the image panels
will start or stop a movie in the forward direction in that
panel.
Clicking the third mouse button in one of the image panels
will start or stop a movie in the backward direction in that
panel.
Actions in Model Mode:
Clicking the first mouse button near a model point in the XY
plane will select that point as the current model point. Click-
ing anywhere else will cause the same result as in movie mode.
Dragging with the first mouse button is the same as in movie
mode.
Clicking with the second mouse button in the XY plane will
add a point to the current contour and has no effect elsewhere.
Dragging with the second mouse button depressed will add a
series of points to the current contour.
Clicking with the right mouse button in the XY plane will
move the current model point to that location.
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.
There are also options to control whether the ghost contours are
lighter or darker in color, and to show ghosts from all objects rather
than just from the current object.
AUTOSAVE AND BACKUP FILES
The program will back up the current model to the file
model_file_name#autosave# every few minutes. If no model file has been
saved yet, the name of the autosave file is just #autosave#. The
autosave file is eliminated whenever the model is saved, and when the
program exits normally. The first time that you save a model file, the
existing model file will be renamed to model_file_name~, and any exist-
ing file by that name will be deleted. This backup file will not be
overwritten each time that you save thereafter, so that it will pre-
serve the state of the model when 3dmod was started.
Automatic saves can be controlled or disabled by using the 3dmod Pref-
erences dialog or by setting environment variables (obsolete). The
Preferences dialog has a checkbox to enable autosaving, a spin box to
set the number of minutes between automatic saves, and a text box to
specify a directory in which the autosave file will be written. Thus,
one can specify a directory on a local disk (e.g., /usr/tmp) and avoid
the long delays required to write a large model to a disk over the net-
work. Formerly, these features were controlled by the IMOD_AUTOSAVE
environment variable, which specified the minutes between autosaves or
0 to disable autosaving, and by the IMOD_AUTOSAVE_DIR variable. If
these variables are defined, the Preferences dialog will initially show
their values; but once the user has changed these settings through the
Preferences dialog, the environment variables will be ignored.
IMAGE LIST FILES
An image list file can be entered instead of an image file on the 3dmod
command line. This ASCII file can specify a series of image files that
represent different times, so that one can step through time as well as
X, Y, and Z. An image list file can also be used to specify both an
image file and a piece list with a single file. In either case, the
cache is turned on. Lines beginning with # are treated as comments and
ignored.
The format of the file is:
IMOD image list [must be the first line of the file]
VERSION 0 or VERSION 1 [must appear somewhere in file]
To specify a series of files at different times, include a series of
entries of the form (the second entries for time labels are optional,
and default label if it is omitted is the image filename):
IMAGE image_filename
TIME time_label [The label can be any desired text]
If the first file might not exist, precede the list of images with a
line:
SIZE nx,ny,nz [nx,ny,nz are the image dimensions
to be assumed for the first file]
To specify an image file and piece coordinates, include the following:
IMAGE image_filename
XYZ [on a line by itself]
x y z [piece coordinates, one line per section]
. . .
To load files that are located in another directory, include the fol-
lowing before the IMAGE lines for the respective files. This entry can
occur more than once.
IMGDIR path_to_image_directory
PLUGIN ENVIRONMENT
3dmod will load special plugin libraries that are in the directory
pointed to by the IMOD_PLUGIN_DIR environment variable. In addition,
the directory defined by $IMOD_CALIB_DIR/plugins, as well as the direc-
tories /usr/local/IMOD/plugins and /usr/freeware/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. The best place to place custom plugins would be
/usr/local/ImodCalib/plugins.
AUTHORS
Jim Kremer
David Mastronarde
SEE ALSO
Viewing programs 3dmodv, midas
Model conversion imodinfo, imod2vrml
Image conversion tif2mrc, raw2mrc, dm2mrc, mrc2tif
BUGS
Please email all bug reports to mast at colorado dot edu.
BL3DEMC 3.11.2 3dmod(1)