xfmodel(1)                                                          xfmodel(1)



NAME
       xfmodel - solves for transformations and applies them to models

SYNOPSIS
       xfmodel  [options]  input_model  output_file

DESCRIPTION
       Xfmnodel will take an IMOD model, and either a) use corresponding
       points in two sections to obtain a transformation
          between the sections, or b) transform the points in the model to
       match a new alignment of images

       To solve for transforms, the model objects should consist of corre-
       sponding points in two or more successive sections.  The program con-
       siders each pair of successive sections independently.  If an object
       contains two points in the same section, the program will take the
       point whose Z value is closer to that of the other section in the pair.

       The program can "edit" an existing list of f transforms (transforms
       that relate each section to the previous one).  That is, the model may
       have points from only a few sections, or one may specify which sections
       to find transforms for, and the program will output a list containing
       new transforms for those sections and transforms from the existing list
       for the rest.

       In solving for transforms, the model can be built on unaligned images
       or on images that have been aligned with a previously existing set of
       transforms.  In the latter case, if you specify the file of g trans-
       forms that were used to prealign the images, then the new transforms
       will apply to the original images; otherwise, the new transforms are
       incremental to the first alignment and would apply to the prealigned
       images.

       When the program solves for the transformation between a pair of sec-
       tions, it applies the transformation to the points on the second sec-
       tion of the pair, and computes the displacement, or deviation, between
       each point and the corresponding point on the first section of the
       pair.  It then reports the mean deviation for all of the points, the
       maximum deviation, and the object number of the point with maximum
       deviation.  In addition, you may elect to have a complete report of the
       deviations of all points for particularly bad sections.  If you choose
       this option, you control which sections are reported by specifying cri-
       terion values for the mean and maximum deviations; the full report will
       be made for any sections with mean or maximum deviations greater than
       the respective criteria.

       If the images are montaged, this is specified by entering the the name
       of the file of piece coordinates.  The Z values in this list of pieces
       are used to establish the correspondence between Z values in the model
       and transform number in the list of transforms.  If the image is miss-
       ing some sections, you should specify whether the transform lists con-
       tain a transform only for each existing section or a transform for each
       section number, including the missing sections.  The choice here will
       be applied both to lists of existing transforms that are read in and to
       the list that is computed by the program, if any.  In either case, if
       there are model objects that bridge a gap over missing sections, the
       program can compute a transform between the sections on either side of
       the gap.

       Instead of solving for transforms between pairs of adjacent sections,
       the typical mode of operation, the program can solve for transforms
       between a single specified section and each other section.

       It is possible to find the X/Y translation alone that best aligns the
       set of points on a section to those on a previous section.  The result-
       ing transformations (which involve no rotations or size changes) can be
       used in a second stage of model alignment to remove progressive shifts
       in position while retaining trends in size and rotation.  It is also
       possible to find the translation and rotation alone that best aligns
       two sections.  The resulting transformations (which involve no size
       changes) can be used in a second stage of model alignment to remove
       progressive shifts in position and rotations while retaining trends in
       size.  Finally, you can also obtain transformations that include trans-
       lation, rotation, and magnification change but no stretch.

   Transforming Models
       A model that was built on unaligned images can be transformed to match
       with aligned images.  A model built on aligned images can be back-
       transformed to match the raw, unaligned images, or it can be trans-
       formed to match a new alignment of the images.  This behavior is con-
       trolled by specifying the transforms used for prealignment.  The possi-
       bilities can be illustrated with operations on a fiducial model for
       tilt series alignment, which was built on images prealigned with the
       transforms in setname.prexg.  Tiltalign produces transforms in set-
       name.tltxf that could be used to bring the prealigned images into final
       alignment.  To transform the fiducial model to the final aligned stack,
       use:
         xfmodel -xf setname.tltxf setname.fid setname.fidali

       Once setname.tltxf and setname.prexg are multiplied to obtain the full
       alignment transforms setname.xf, the same result is achieved with:
         xfmodel -xf setname.xf -pre setname.prexg setname.fid setname.fidali

       To transform the model back to the raw stack, use:
         xfmodel -back -pre setname.prexg setname.fid setname.fidunali

       When a distortion field is specified, it is important to indicate the
       prealignment transforms, if any, because the distortion field is accu-
       rate only for the original images.  The program can behave in 4 differ-
       ent ways:
         1) -distort only: the model is assumed to be built on unaligned
       images and is simply undistorted (or redistorted, if -back in included)
         2) -distort and -xform: the model is assumed to be built on unaligned
       images and is undistorted then transformed by the given transforms.
         3) -distort and -prealign: the model was built on prealigned images.
       It is back-transformed, undistorted, then re-transformed into alignment
       with undistorted prealigned images.
         4) -distort, -prealign, -xform: the model was built on prealigned
       images.  The transforms specified by -xform must be ones that would
       apply to original rather than prealigned images.  The model is back-
       transformed by the prealignment transforms, undistorted, then re-trans-
       formed by the transforms specified by -xform.

       Each linear transformation in a transform file is specified by a line
       with six numbers:
         A11 A12 A21 A22 DX DY where the coordinate (X, Y) is transformed to
       (X', Y') by:
         X' = A11 * X + A12 * Y + DX
         Y' = A21 * X + A22 * Y + DY

OPTIONS
       Xfmodel uses the PIP package for input (see the manual page for pip)
       and can take input interactively only for options available when the
       program was converted to PIP input, to maintain compatibility with old
       command files.  The following options can be specified either as com-
       mand line arguments (with the -) or one per line in a command file or
       parameter file (without the -).  Options can be abbreviated to unique
       letters; the currently valid abbreviations for short names are shown in
       parentheses.


       -input (-in) OR -InputFile     File name
              Input model file to be transformed, or from which transforma-
              tions will be found.

       -output (-o) OR -OutputFile    File name
              Output file, either transformed model or list of transforma-
              tions.

       -image (-im) OR -ImageFile     File name
              Image file that model was built on, used to determine center
              coordinate for transformations.  If neither this nor Center-
              InXandY are entered, the image size will be used from the model
              header.

       -piece (-pi) OR -PieceListFile      File name
              Name of piece list file for a montaged image file

       -allz (-a) OR -AllZhaveTransforms
              When there is a list of piece coordinates that has gaps in the Z
              values, use this entry to indicate that transform files have
              transforms for all Z values; otherwise the files will be assumed
              to have matching gaps in Z.

       -center (-ce) OR -CenterInXandY     Two floats
              Center coordinates of image in X and Y.  If neither this nor
              ImageFile are entered, the image size will be used from the
              model header.

       -transonly (-t) OR -TranslationOnly
              Solve for transformations that include only translations in X
              and Y.

       -rottrans (-r) OR -RotationTranslation
              Solve for transformations that include rotations and transla-
              tions.

       -magrot (-m) OR -MagRotTrans
              Solve for transformations that include magnifications, rotations
              and translations, i.e. no stretch.

       -sections (-se) OR -SectionsToAnalyze    List of integer ranges
              List of sections to find transformations for. identified by the
              second one of each pair, numbered from 0.  The default is all
              sections.

       -single (-si) OR -SingleSection     Integer
              Align all sections to a single reference section with the given
              section number.

       -full (-f) OR -FullReportMeanAndMax      Two floats
              A detailed report will be printed for any section that exceeds
              either the given mean deviation or the given maximum deviation.

       -prealign (-pr) OR -PrealignTransforms   File name
              File of g transforms that were used to prealign the images on
              which the model was built

       -edit (-e) OR -EditTransforms       File name
              Name of file with existing f transforms to be replaced by any
              transforms that are solved for

       -xforms (-x) OR -XformsToApply      File name
              File of g transforms to apply to transform the model

       -useline (-use) OR -UseTransformLine     Integer
              Line number of single transform to apply to all points in model,
              regardless of their Z values.  Line numbers start at 0.  This
              option can be used only when forward or back-transforming the
              model.  This option will be invoked automatically if there is
              only one transform in the file.  If prealignment transforms are
              specified when transforming or undistorting a model, they will
              be applied as usual, with a separate transform used for each Z
              value.

       -chunks (-ch) OR -ChunkSizes   List of integer ranges
              If the model consists of a set of blocks in Z, such as a model
              built on a set of serial tomograms, then this option can be used
              to apply one transform per chunk of Z values.  Enter a list giv-
              ing the number of sections in each chunk.  Z values beyond the
              total of these chunk sizes will not be transformed.  The same
              chunk structure will be used when applying prealignment trans-
              forms if -prealign is entered.

       -back (-ba) OR -BackTransform
              If no distortion field is involved, apply the inverse of the
              transforms specified by -prealign or -xforms.  Either of these
              two options may be used to specify transforms, but not both.  If
              a distortion field or mag gradient is specified, this option can
              be used to transform a model built on undistorted images to
              match original images.  In this case, prealignment transforms
              will be treated differently depending on how they are specified:
              with -xforms, the model will be back-transformed to match the
              raw images; with -prealign, the model will be transformed to
              match prealigned but distorted images.

       -scale (-sc) OR -ScaleShifts   Floating point
              Factor by which to scale X/Y translations in the transforms
              before applying them.  Use this option if a set of transforms is
              appropriate for images at one scale but the model was built on
              images at another scale.  For example, if images are scaled by
              binning, the factor would be the binning of the images that the
              transforms apply to, divided by the binning of the images on
              which the model was built.

       -distort (-d) OR -DistortionField   File name
              File with image distortion field to be applied in transforming
              model.  If BackTransform is specified, the model will be redis-
              torted, i.e.  transformed to match original distorted images.

       -binning (-bi) OR -BinningOfImages       Integer
              The camera binning at which images were taken.  This entry may
              be required when undistorting if the program cannot deduce the
              binning unambiguously.

       -gradient (-g) OR -GradientFile     File name
              File with magnification gradients to be applied for each image.
              This should be a file listing the tilt angle, the percent magni-
              fication change per micron of Z height, and the degrees of rota-
              tion per micron of Z height for each image, such as is produced
              by Extractmaggrad.  The mag gradient correction is applied
              before a distortion field correction and before any transforma-
              tions.

       -param (-pa) OR -ParameterFile      Parameter file
              Read parameter entries as keyword-value pairs from a parameter
              file.

       -help (-h) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input.


   INTERACTIVE INPUT
       If the program is started with no command line arguments, it reverts to
       interactive input with the following entries:

       Name of image file that model was built on, or blank line to enter cen-
       ter coordinates instead

       IF you entered an image file name, next enter the name of a piece list
       file if the image is a montage, otherwise enter a blank line

       OR if you did not enter an image file, next enter the X and Y index
       coordinates of the center of the image (NX/2, NY/2)

       IF there are gaps in the Z values described by the piece list, next
       enter 0 if transform files have transforms only for the Z values that
       exist, or 1 if they have transforms for all Z values

       Name of model file

       Enter one of:
         -1 to back-transform the model to fit a raw image stack
         0 to find linear transformations
         1 to transform the model with a set of transformations
         2 to find X/Y translations only
         3 to find translations and rotations
         4 to find translation, ratation, and mag change

       IF you entered any option other than -1 to back-transform, next enter 0
       if the model was built on raw sections, or the sections that you want
       to further transform; or 1 if the model was built on pre-aligned sec-
       tions and you want to reference transforms to the raw sections

       IF you are back-transforming OR if you entered 1 to the last query,
       next enter the file name of the g transforms used to pre-align the sec-
       tions

       IF you are transforming or back-transforming the model, next enter the
       name of the output model file.  This is the final entry for option -1

       IF you are transforming, enter the name of the file with transforms to
       apply; this is the final entry for option 1

       IF you finding transforms instead, continue with the following entries:

       Name of file with existing f transforms to be replaced by any trans-
       forms that are solved for

       Name of output file for new f transforms

       A list of section numbers to find transforms for (the second section of
       each pair, sections numbered from zero), or / to find transforms for
       all sections with data in the model, or -999 to find transforms of all
       sections relative to a single section

       IF you entered -999, next enter:
          The number of the single section
          The real list of transforms to find sections for, or / for all

       1 for complete reports of the deviations for each point on sections
       with bad fits, or 0 for no detailed reports

       IF you entered 1, then enter a criterion for the mean deviation and a
       criterion for the maximum deviation; a complete report will be given
       for any section that exceeds either criterion.

HISTORY
       Written by David Mastronarde, 1988
       DNM 7/20/89  changes for new model format
       DNM 1/10/90  have it transform only existing model points, not all
       points in p_coord array, to avoid bad Z values
       DNM 5/28/90  fix bug in rounding 0.5 values, implement ability to
       transform relative to a single section.
       DNM 3/31/92  Implement translation only finding
       DNM 5/1/92   Implement translation and rotation only finding
       DNM 4/24/95 changed model reading/writing to be portable
       DNM 9/23/97  Add translation, rotation, and mag change finding
       DNM 9/4/02  Change to take scaling from model and scale properly
       DNM 12/27/03 Convert to PIP input, add distortion correction

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                          xfmodel(1)