Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

XFTOXG(1)							 XFTOXG(1)

NAME
	xftoxg - Converts transforms between sections into alignment transforms

SYNOPSIS
	xftoxg [options] input_file [ouput_file]

DESCRIPTION

  XFTOXG takes a list of transformations (f) from each section to
  the previous one, and computes a list of xforms (g) to apply to each
  section to obtain a single consistent set of alignments.  Transforms can be
  simple 6-component linear transforms or warping transformations.

  Three different modes of operation can be selected.	 In the first, all
  sections will be transformed to a single position in the "center" of
  the series.	 Here "position" refers to the entire set of parameters
  describing the transformation, i.e. not just the x,y coordinates but
  the rotation and stretch as well.  This mode will remove any consistent
  trends in the data stack, such as a progressive rotation, compression or
  shift.  This mode, sometimes referred as giving a global alignment, can be
  invoked with the option "-n 0".

  In the second mode, the "center" position is allowed to change progressively
  over the series.  For each section, the program fits polynomials to the
  transformation parameters over the selected distance (centered on the given
  section, if possible), and uses these polynomial fits to define the position
  to which that section should be transformed.  This mode will retain trends
  in the data stack that occur over the range of the specified distance.  This
  is the default mode of operation, with linear fits over 7 adjacent
  sections.
         
  In the third mode, the "center" position is assumed to change
  progressively over the whole series, based on a polynomial fit to the
  series, and a transformation will be computed for each section that will
  align it to a fitted shifting center position.  If a polynomial order of 1
  is selected, the center position will shift linearly from one end to the
  other of the data stack.  This mode will retain trends in the data stack
  to the extent that they can be fit by the order of polynomial chosen.  For
  example, if order 1 is chosen, the fit is a linear one, and the resulting
  transforms will retain trends that occur at a constant rate from one end
  to the other.

  It is also possible to do a mixed or hybrid alignment in which trends are
  retained for some parameters while they are eliminated for others.  Trends
  will be eliminated for X and Y translations, and can optionally be
  eliminated for rotations and overall size changes.  The most appropriate
  choice would be to eliminate trends for translations and rotations, unless
  the rotation trends in the data are meaningful and should be preserved.
  This hybrid method can be used with either local or global polynomial fits
  (the second or third mode of operation).

  Sometimes a small minority of sections are rotated at a large angle from
  the rest.  Including such sections in the computation of the "center"
  position would skew the average rotation.  In such cases, the "-range"
  option can be used to exclude sections whose rotation angles fall outside
  of the given range from the averaging and fitting procedures.  For example,
  if a range of 45 degrees is given, then the program will find the largest
  group of sections whose angles span a range of 45 degrees or less, and use
  only these sections to compute the global average alignment.

  The input file can contain warping transformations, which can be specified
  either as displacements at a set of control points, or as displacements on a
  regular grid.  In either case, the output will consist of a regular grid of
  displacements, with the same grid locations for every section.  The program
  first analyzes each warping transform to remove the linear component from it
  and combine that with the separate linear transformation.  The linear
  transforms are treated as usual, according to the various options that are
  given.  The remaining warp transforms are currently analyzed in a way
  similar that the way in which a global alignment is produced for linear
  transforms.  This means that trends will be retained, which could be
  problematic.  This analysis is done by multiplying the warping transforms
  that remain after removing the linear component to form cumulative products,
  which are then multiplied by the inverse of the average transform.

  To do the averaging and fitting, the program converts the A matrix of the
  g transforms to the "semi-natural" parameters: global rotation and
  magnification, and differences between Y and X axis rotation and stretch.
  This conversion allows the hybrid alignments to be done.  It also means
  that if input transformations involve only a restricted set of these 
  parameters (e.g., rotation only), this restriction will be retained in the
  final g transforms.

  The ability to use both the local fits and fits of order higher than 1 is
  somewhat redundant.  If local fitting is used, start with order 1 and go
  to higher orders only if necessary.
	  
  Xftoxg uses the PIP package for input (see the manual page for pip)
  and can take also input interactively 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 (without the
  -):

 -input OR -InputFile   File name
    Input file with f transforms

 -goutput OR -GOutputFile   File name
    Output file for g transforms.  If an output filename is omitted and the
    input filename ends in xf, the input filename will be used as output with
    the last letter converted from f to g.

 -nfit OR -NumberToFit   Integer
    Number of adjacent sections to fit, 0 for global alignment, or 1 for fit
    to all sections

 -ref OR -ReferenceSection   Integer
    Do a global alignment to the given section; this will give the reference
    section a unit transform and keep it from being transformed.  Sections are
    numbered from 1.

 -order OR -OrderOfPolynomialFit   Integer
    Order of the polynomial fit to the data. The default is 1 (linear fit).

 -mixed OR -HybridFits   Integer
    Number of parameters to eliminate trends for with a hybrid alignment: 2
    for translations only, 3 for rotations also, 4 for size changes also.

 -range OR -RangeOfAnglesInAverage   Floating point
    Compute the global average center position, and the center position for
    local fits, using the largest group of sections whose rotation angles fall
    within the given range.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.

  If the program is started with no command line arguments, it reverts to
  interactive  input with the following entries:
   
  0 to align all sections to a single average central alignment, 1 to align
  to an average alignment fit to a single polynomial, N > 1 to align each
  section to an average alignment fit to the nearest N sections, or -1 or
  -N to do a hybrid of central and shifting alignments with fits to a single
  polynomial or to locally fitted polynomials
         
  IF you entered a negative number, next enter 2 for central alignment of
  translations only, 3 for central alignment of translations and rotations,
  or 4 for central alignment of translations, rotations and size changes
         
  IF you entered a nonzero number to the first query, next enter the order
  of the polynomials to fit (1 for linear fits)
         
  Name of input file of F transforms
         
  Name of output file of G transforms

HISTORY
  Written by David Mastronarde, 1988
  Added hybrid method, 7/26/01
  Converted to PIP input, 1/25/04
  Added support for warping transforms, June 2011