midas(1) General Commands Manual midas(1)
NAME
midas - manual image alignment for MRC files.
SYNOPSIS
midas [options] image_file [transform_file]
DESCRIPTION
Midas allows one to assess and adjust the alignment between pairs of
images. It is typically used to align images from serial sections and
to correct errors in a pre-alignment of tilt series images by cross-
correlation. It can also be used to adjust the alignment between adja-
cent pieces in a montaged image. There are interactive controls for
adjusting translation, rotation, magnification (scale), and stretch
along an axis. Linear transformations are used to apply the transla-
tion, rotation or distortion. This means that the same amount of
translation, rotation or distortion happens everywhere in an image. A
nonlinear transformation, or warping, can be added by marking selected
points and locally aligning images at those locations.
All transformation parameters can be adjusted by dragging a point on
the image with the mouse. The help menus describe the functions of
each mouse button, as well as the operation of the various controls and
hot keys. The controls also have tooltips with brief summaries of
their function.
Midas also allows one to adjust the brightness and contrast of each
image independently to ease comparisons. The program can produce a
copy of the image stack with these individual contrast changes applied
(but not with the transformations applied).
The input image files for Midas must be MRC files. They can be byte,
integer, or real images, and can also be RGB images, which will be dis-
played in grayscale. The latter option can be used to align model con-
tours displayed on an image by snapshotting the Zap window in 3dmod
and creating a color MRC stack with tif2mrc.
Information on using Midas with a high-DPI monitor is provided in sec-
tion 1.13 of the IMOD Guide.
Alignment modes
Midas maintains a list of transformations, one for each section in the
image file. At any given time, one section is the "current" section,
it is displayed with its transformation applied to it, and any adjust-
ments in alignment modify that transform. Another section is the "ref-
erence" section to which the current section is being aligned. Other
aspects of the way that transforms are treated depend on which mode
Midas is operating in: local, global, or reference.
In local alignment mode, each image section is usually aligned to the
previous section. The transformations in this mode are sometimes
referred to as "xf" transforms, which are suitable only for aligning
one image to another. The program xftoxg is used to convert xf
transforms into the "xg" transforms that are suitable for transforming
the whole image stack into alignment. In this mode, Midas displays the
reference section without transforming it, and any changes in transfor-
mation are applied only to the transform of the current section.
In global alignment mode, each image section is effectively aligned to
the entire image stack. The transformations are of the global (xg)
type, ready to use to transform all of the images into alignment.
There are two differences in program operation that achieve this:
first, the reference section's transformation is applied whenever it is
displayed; second, when you modify the transform of the current sec-
tion, the transforms of all following sections are changed by the same
amount. Global alignment may be suitable for aligning small sets of
sections because of its simplicity. However, it is not recommended for
larger numbers of sections (more than 20-30). Local alignment followed
by the use of xftoxg is preferable because it will automatically
keep the aligned images from drifting out of the field of view. It
will also preserve trends in the data; for example, if you align using
features that gradually get smaller, global alignment may eliminate
this size change, while local alignment will preserve it, even if every
transform over the series includes a size change.
If you do want to use global alignment mode, you may want to start in
the middle of the image stack and work forward from there. Then, turn
off the "Keep Curr-Ref Diff" box, make the middle section be the refer-
ence again and make the previous section be the current section. Turn
the "Keep Curr-Ref Diff" box back on again and work backwards to the
beginning of the stack.
Reference alignment mode is used to align each image in a stack to a
single image that may be in another image file. The other image file
is specified with the -r option. In this mode, advancing or backing up
by a section changes only the current section unless you turn on the
"Keep Curr-Ref Diff" option; with that option off, the reference sec-
tion is changed only by typing a new number into its text box. If your
reference section happens to be in the same file as the images being
aligned to it, then you can either specify that file as both the refer-
ence and the image file, or start Midas in local alignment mode then
turn off the "Keep Curr-Ref Diff" box and set the reference and current
sections independently.
In global or reference alignment mode, a menu option can be used to
transform a model file using the transformations available for each
section, just as with imodtrans.
Warping Images
Warping can introduced by adding a set of points, referred to as con-
trol points, and applying an appropriate shift at each point. This
warping is in addition to whatever linear transformation has been set.
To start adding points, turn on "Add/edit warp points". You can then
add a point with the middle mouse button and shift images into align-
ment at that location with either the left mouse button, the X and Y
translation buttons, or the arrow keys. The shift at the point is
shown on the lines with the X and Y translation buttons, while the
translation component of the linear transformation is shown on a sepa-
rate line.
Until there are at least four points, shifting a control point will
just change the linear transformation. With one point, it will shift
the whole image; with two points, shifting at one point will rotate and
magnify the image to keep it stationary at the other point; with three
points, shifting at one point will stretch the image to keep it aligned
at the other two points. You can thus use three points in this way to
set a linear transformation. If the linear transformation is already
set, you should probably add four or more points before shifting any of
them. Once there are at least four points, you can no longer turn off
the option to edit warp points because the linear translation is fixed.
Make the control points widely spaced and distributed over as much of
the area as possible. The program will warp the image inside the
region bounded by the control points but has to use extrapolated trans-
formations outside that region.
A control point is considered to be fixed on the reference image. You
can thus add the point at a recognizable feature on the reference
image, then shift the current image to center that feature on the
point. You can change the fixed location of the point by clicking with
the right mouse button. The currently active point is shown in yellow
and other points are shown in red. Click with the left mouse button to
select the nearest point as the active point. There is a menu entry
and a hot key for deleting the current point.
Warping transformations can be specified only in local or reference
alignment mode. Xftoxg can convert them to global transformations.
They can be used interchangeably with linear transforms in Xfprod-
uct(1), Xfinverse, Newstack, Blendmont, Xfmodel, and serial
tomogram joining.
Storage of Transforms
The transformation for the current section is automatically stored on
the internal list of transforms when you change to a different section.
Before changing sections, you can restore the transform to the stored
value using an entry in the Edit menu. There are also menu entries to
reset to the unit transform (no translations, rotations, etc.) and to
store the current transform on the internal list. You can use the lat-
ter to save a transform that you like before trying to improve on it.
If the name of a file of transforms is entered after the image filename
when first starting Midas, then Midas will read transforms from this
file, and images will initially be displayed with these transforms.
This file then becomes the default file into which Midas will save
transforms. Transforms can be saved into a different file with the
File menu entry "Save As". After doing so, that file becomes the
default file for successive save operations. In either case, the first
time that Midas saves to a file, it will make a backup of an existing
file by that name by adding ~ at the end. If the name of a transform
file that does not yet exist is entered on the command line, Midas will
create and save into that file.
Using Global Rotations and Cosine Stretching
Midas can rotate all images by a common amount and allow you to adjust
transformations in the rotated images. This ability, invoked with the
-a option, can be used to make the tilt axis vertical when aligning a
tilt series. When the program is started in this mode, there is a con-
trol for adjusting the global rotation angle. There is also a check
box to constrain translations with the mouse to the X direction, which
is usually the only direction that needs fixing in a tilt series pre-
aligned by correlation. This rotation provides a convenient way to
look at tilted images but should not affect the alignment; the trans-
formations output by the program are independent of the global rotation
angle. However, the X and Y translations that are displayed and
adjusted in Midas are relative to the rotated images and will change
with the angle. Global rotations can be used in local or global align-
ment mode.
Midas can also apply cosine stretching of images if a file of tilt
angles is provided with the -t option. It will stretch the current
image by the ratio of the cosines of the current and reference image
tilt angles. The stretch is always along the X axis after applying a
global rotation, so invoking this option turns on the global rotation
mode. With such a stretch, it should be easier to find the shift that
aligns the images. If stretched images do not line up well, even when
looking just at features on one Z plane, then an offset can be applied
to the tilt angles. As with global rotation, this stretching does not
affect the alignment transforms output by the program, but the X trans-
lation that is displayed in the program does depend on the stretching.
Cosine stretching cannot be used in global or reference alignment mode.
Aligning Chunks of Sections
Midas has another mode of operation that can be used to align tomograms
of serial sections. This is referred to as "chunk" alignment because
sections are considered in chunks, where a chunk corresponds to all of
the slices from one tomogram. In this mode, all of the sections in a
chunk are given the same transformation alignment, so there is only one
transformation per chunk. This mode is a variant of the local align-
ment mode, with the additional constraint that the alignment is always
between adjacent pairs of chunks. When adjusting the transformation
between a pair of chunks, you can view any pair of sections from the
two chunks, and you are also free to scroll through the slices in a
chunk to discern trends in position. Activate this mode by specifying
the number of sections in each chunk with the -c option. To get one
transformation per tomogram, do not divide the slices from the top and
bottom of tomogram into separate chunks.
Fixing Montage Overlaps
When the pieces of a montage need to be shifted into registration with
each other, Blendmont uses the image displacements in the overlap
zones between adjacent pieces to determine how to shift the pieces.
Sometimes Blendmont does not determine a displacement correctly, lead-
ing to erroneous registration of the pieces. To use Midas to correct
the displacements, start Midas with the -p option followed by the name
of the piece list file. After the montaged image file name, in place
of a transformation file, enter the name of the edge correlation dis-
placement (.ecd) file produced by Blendmont. You can then display and
adjust the overlap between any pair of adjacent pieces on any section.
Overlap zones are referred to as edges and are of two types: X edges
between pieces in a horizontal row, and Y edges between pieces in a
column. X edges are numbered sequentially from left to right, first in
the bottom row, then in the next row, etc. Y edges are numbered from
bottom to top in columns, with the leftmost column being the first one.
The numbering is independent of whether there are pieces missing (e.g.,
the first X edge will be numbered 3 if there are two pieces missing to
the left of it). The edge number controls, just below the section con-
trols, allow one to select any given edge by this number, but they also
allow you to see and select an edge by the X and Y frame number of the
lower piece (the one to the left of an X edge, or below a Y edge).
To find edges that need fixing, it is usually more convenient to use
the buttons provided for selecting one of the edges with the worst dis-
placement errors. However, in cases where there are only a subset of
mismatched edges that matter, it may be more convenient to find these
edges in 3dmod and navigate to them in Midas. A button for this pur-
pose should be available if a "preblend" montage was built in the Etomo
interface. Specifically, there must be either a montage file named as
the root name of the input file plus "_preblend.mrc", or a file entered
with the -mb option; and there must be either a file named as the root
name plus ".alipl" or a file entered with the -mcoption. Once 3dmod is
open, the current point can be placed in the middle of a particular
edge, and the button in Midas can be used to display that edge. Also,
Midas will tell 3dmod when a different edge or section is displayed,
and 3dmod will move the current point to the middle of that new edge.
When two pieces are displayed, their X and Y translation values corre-
spond to the image displacement at that edge, originally measured by
Blendmont and possibly adjusted within Midas. The displacements for
all of the edges are used to determine the optimal shifts of the piece.
When these shifts are applied to the pieces, they produce displacements
at all of the edges, displacements that may or may not match the indi-
vidual displacements measured from the images there. A mismatch at an
edge is a displacement error, which has X and Y components. Large dis-
placement errors arise when the displacement measured at an edge does
not align the images there. Manually aligning images at an edge with a
large error will thus reduce the error there and also at other edges
involving the same pieces.
If there is only one edge with a mismeasured displacement, then solving
for the shifts using all of the other edges while leaving out the one
in question will often imply a perfectly good displacement at that
edge. The difference between this displacement and the measured one is
called the "leave-out error", and pushing the "Apply Leave-out Error"
button will adjust the edge to the displacement implied by all of the
other edges. If an edge shows a visible image mismatch that appears to
correspond to the leave-out error, then pushing this button is a useful
shortcut for aligning the images by hand.
One must be careful to examine both of the edges with the top two
errors when the erroneous edge involves a corner piece in the montage,
a not infrequent occurrence. In this case, the error will be equally
divided between the two edges of the corner piece, even though there is
an erroneous measurement at only one of them. For similar reasons, a 2
by 2 montage with an erroneous displacement will spread the error
equally among all four edges.
If the montage consists of only one row or one column, all errors will
be zero regardless of whether the displacements have been measured cor-
rectly. Visual examination of the edges is the only way to detect and
correct errors in the measured displacements.
When there are more than 10 pieces, the program can find a more robust
solution for the shifts between pieces that can give less weight to or
eliminate edges that have obviously erroneous displacement. This is
referred to as robust fitting. Its main value in Midas is to make the
edges with bad diplacements show up with particularly high errors. The
degree of robustness is controlled by a criterion value with a default
value of 1. With the default value, some edges that have good dis-
placements may be downweighted inappropriately and thus show up as hav-
ing a high error even though they are well-aligned. A higher criterion
will prevent this from happening but may fail to identify some bad
edges as outliers (values up to about 1.5 should be tried).
If an edge with a good alignment shows up as having a large error with
robust fitting enabled, use the following strategy:
1) Continue to fix or exclude other edges with high errors. The error
of the well-aligned edge may drop as other errors around it are
resolved.
2) If the well-aligned edge still has a high error after other edges
with high errors have been fixed, examine all of the edges around the
two pieces below and above this edge. You may find a small misalign-
ment.
3) If you still can not find a misaligned edge, raise the fitting cri-
terion until the error becomes normal, or ignore the large error. Note
that if you are going to use the robust fitting option in Blendmont(1),
you would need to set the criterion to this same value to prevent a
misalignment across this edge.
OPTIONS
Midas accepts some Qt options (such as -style) and the following
options.
-g Start Midas in global alignment mode. The default is local
alignment mode.
-r filename
Load a reference image from a file with the given filename.
This reference image can be used for aligning an image stack to
the single reference image.
-rz section
This option will select the section number to be used when load-
ing in a reference image with the -r option. The default value
is the first section which is numbered 0.
-c list of sizes
Determine alignment between chunks of sections. Enter a comma-
separated list of the number of sections in each chunk. The
list should add up to the total number of sections in the image
file. When chunks are entered in this way, the reference or
current section can be set to any section within a chunk.
-cs list of sizes
Determine alignment between chunks of sections from samples near
the boundaries between chunks (e.g., tomograms corresponding to
physical sections). Enter a comma-separated list of the number
of sections in each sample, where the first and last chunk have
only one sample and other chunks have two samples. The list
should add up to the total number of sections in the image file.
When chunks are entered in this way, the reference and current
section are constrained to stay within a sample.
-B factor
Bin images by the given factor when reading them in. The trans-
lation component of the transformation shown and adjusted in the
program will be smaller by this amount. Translations will be
scaled down when read in from a file and scaled back up when
written out to file. Errors shown when fixing montage overlaps
will also be smaller by the binning factor. Entering this
option overrides automatic binning specified with the environ-
ment variable MIDAS_BIN_TO_TARGET (use "man imodenv" or "imod-
help" - Other Man Pages - IMOD Environment Variables for
details).
-p filename
Load piece coordinates for a montaged image file from the given
filename and enter montage fixing mode. The final argument on
the command line would ordinarily be the .ecd file produced by
Blendmont, but it is possible to open a montage without such
a file.
-mb filename
Use the given montage file for opening 3dmod to find mis-
aligned edges, as described above. This entry is not needed if
a file named by the root name of the input image file plus
"_preblend.mrc" is present.
-mc filename
Use the given file of aligned piece coordinates from Blend-
mont(1) for opening 3dmod to find edges. This entry is not
needed if a file named by the root name of the input image file
plus ".alipl" is present.
-C size
Set the cache size to the given number of sections. Sections
are read from the file as needed, intensity-scaled to be stored
as bytes, and kept in a cache. By default, the cache is limited
to about 1 gigabyte, or at least big enough for 4 sections. If
your file has more than this number of pixels, and you have more
memory available, you can use this option to provide enough
cache for all sections. If you have less than this amount of
memory available and your file has more pixels than there is
memory, you should enter an appropriate size to avoid disk swap-
ping.
-s min,max
Scale the image intensities when reading from the file, so that
the range from min to max will be scaled to range from 0 to 255
when the section is stored in the program.
-b size
Set the initial size of the blocks for transforming the current
image. The larger the block size, the faster the display, but
quality will suffer, especially for images that are rotated sub-
stantially. A size of 0 will turn on image interpolation.
-a angle
Display all images with a global rotation specified by angle.
When the program is started with this option, the angle can be
adjusted if necessary with a spin box control.
-t filename
Load tilt angles from this file to allow cosine stretching of
the higher tilt image of a pair.
-o filename
Save transforms to a file with the given filename instead of to
the file that transforms were read from.
-l size,limit
When fixing montage overlaps, set the initial values for corre-
lation box size and shift limit to the given values. Use an
entry of 0 to use the default for one value set just the other
value.
-e number
When fixing montage overlaps, show the given number of buttons
with the highest errors (between 2 and 10).
-O 2 letters
Specify the colors for the previous and current image in overlay
mode. The colors must be two of r g b c m y which stand for
red, green, blue, cyan (green + blue), magenta (red + blue), and
yellow (red + green). The two letters must specify different
channels; e.g., rc will work and rm will not. The default over-
lay colors are magenta and green (mg).
-D Run in debug mode, which means do not run the program in the
background.
-q Suppress reminder to rebuild edge functions when exiting after
fixing montage edges.
FILES
The linear transformation files that Midas uses are in the following
format. The files are in ascii format with one line for each image in
the image stack. Each line contains 6 numerical parameters that are
used to calculate the linear transformation.
A11 A12 A21 A22 DX DY
Where for each pixel with the coordinates (X, Y) a new location (X',
Y') is given by the equations below (Xc, Yc is the center of the
image).
X' = A11 * (X - Xc) + A12 * (Y - Yc) + DX + Xc
Y' = A21 * (X - Xc) + A22 * (Y - Yc) + DY + Yc
Warping transformation files contain a linear transformation of this
form plus the set of control points for each section. Their format is
described in the libiwarp library documentation.
HISTORY
Midas (Manual Image Deformation and Alignment System) was first written
in Fortran for a MicroVax with Parallax graphics by David Mastronarde.
Jim Kremer then wrote a similar program in C for the SGI using first
IrisGL, then X-windows, then OpenGL and Motif. This was originally
named Midas, but was renamed to Manali after Mastronarde ported the
Midas program from the Vax to the SGI. For the next version of Midas,
Mastronarde modified Kremer's Manali to incorporate desirable features
of the old Midas (such as manipulation with the mouse), to implement
new features (such as caching, ability to zoom large images down, abil-
ity to read integer or real mode files, and treatment of a transform
file the way a model file is treated in 3dmod), and to provide com-
pletely new controls, menus, and help windows. In the latest version,
the graphical interface was rewritten in Qt.
SEE ALSO
xftoxg, imodtrans, newstack, blendmont, 3dmod,
tif2mrc
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 midas(1)