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 edge number controls, just below the section controls, 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 displacement errors.

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

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

       -o filename
              Save transforms to a file with the given filename instead of to
              the file that transforms were read from.

       -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                                4.11.0                            midas(1)