Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

XFMODEL(1)							     XFMODEL(1)

NAME
	xfmodel - solves for transformations and applies them to models

SYNOPSIS
	xfmodel [options] input_model output_file

DESCRIPTION
  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
  corresponding points in two or more successive sections.  The program
  considers 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 transforms
  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
  sections, it applies the transformation to the points on the second
  section 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 criterion 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 missing some
  sections, you should specify whether the transform lists contain 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 resulting
  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 translation, 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
  transformed to match a new alignment of the images.  This behavior is
  controlled by specifying the transforms used for prealignment.  The
  possibilities 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 setname.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 accurate
  only for the original images.  The program can behave in 4 different 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-transformed 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 command line
  arguments (with the -) or one per line in a command file or parameter file
  (without the -):

 -input OR -InputFile   File name
    Input model file to be transformed, or from which transformations will be
    found.

 -output OR -OutputFile   File name
    Output file, either transformed model or list of transformations.

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

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

 -allz 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 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 OR -TranslationOnly
    Solve for transformations that include only translations in X and Y.

 -rottrans OR -RotationTranslation
    Solve for transformations that include rotations and translations.

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

 -sections 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 OR -SingleSection   Integer
    Align all sections to a single reference section with the given section
    number.

 -full 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 OR -PrealignTransforms   File name
    File of g transforms that were used to prealign the images on which the
    model was built

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

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

 -useline 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 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 giving 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 transforms if -prealign is entered.

 -back 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 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 OR -DistortionField   File name
    File with image distortion field to be applied in transforming model.  If
    BackTransform is specified, the model will be redistorted, i.e.
    transformed to match original distorted images.

 -binning 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 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 magnification change
    per micron of Z height, and the degrees of rotation 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
    transformations.

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

 -help 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
  center 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
  sections 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 
  sections
  
  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
  transforms 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